Skip to main content
A profile sets what a session can run and see, so agents can share one workspace with different files and commands.
workspace.yaml
A session under researcher reads /data, never sees /data/private, and gets Permission denied for any command commands does not name, builtins such as cd included.

What a profile controls

  • processes scopes are session (the default) or workspace. max is 128 by default; past it a new process fails with Resource temporarily unavailable.
  • A profile’s processes overrides the workspace’s field by field. Its network can only narrow the workspace’s.

Use a profile

A session with no profile gets the one profile: names, else default, else no limits. No command inside a session can change its own profile.

Command rules

commands is a tree that follows each command’s own subcommands and options. Each entry decides allow, ask or deny.
A refused line prints rm: Permission denied and exits 126. A line that waits for approval reads the same until a host approves it. A path refused by paths fails as the command’s own error instead, such as rm: cannot remove '/data/keep/2024.csv': Permission denied, exit 1.

Keys

An entry’s value is allow, ask or deny. Write {decision, reason, paths} to add a reason or to limit the decision to paths, or a list of those to give several decisions for one place.

How a line is judged

  1. Mirage reads the line with the command’s own grammar, so rm -rf, rm -fr and rm --recursive --force are the same line.
  2. The line’s words pick the entry: its subcommands, then its operands, as far as the tree names them. The deepest entry that states a decision gives the result. With no decision anywhere, the line runs.
  3. The options on the line, and their values, can only tighten that result: deny beats ask, and ask beats allow.
So a deeper name can reopen what its parent refuses, as gh pr view does above. An option never can.

Run only the commands you name

  • [ and [[ are commands too. Name them if the session runs tests.
  • A call to a shell function the agent defined is not judged by the root "*". Each command in its body is judged when it runs.
  • commands does not cover executed paths, direct VFS calls or MCP file tools. Limit file access with mounts and paths.

A subcommand

Without "*": deny, only the subcommands you deny are refused: gh: {repo: {delete: deny}} refuses gh repo delete and nothing else.

An option

Options together

An option under an option applies when both are on the line.

Only these options

"-*" decides for every option the tree does not name.

An option’s value

A value can also name options that must be on the line with it. With --request: {values: {POST: {--insecure: deny}}}, curl -X POST -k is refused and curl -X POST runs.

An operand

  • An operand can reopen a denied command. With checkout: {"*": deny, operands: {main: allow}}, git checkout main runs and git checkout dev is refused.
  • An operand entry can hold options and a further operands for the next word. With merge: {operands: {"5": {--admin: deny}}}, gh pr merge 5 --admin is refused and gh pr merge 6 --admin runs.
  • operands goes on a command that has no subcommands.
Keys under operands and values are shell globs. When several keys match one word, an exact key wins. Otherwise the strictest matching glob wins, and "*" answers only for a word no other key matches. Write "[*]" for a literal star. A word that starts with - is an operand only after -- on the line: rm: {operands: {"-rf": deny}} refuses rm -- -rf and leaves rm -rf build alone.

A command without a grammar

Mirage reads a program it has no grammar for, such as one a machine runs, as a name and its operands.
An option key under such a command is refused when the profile loads. To write rules on its options, register it as a CLI.

Paths

A decision with paths speaks only for the paths it covers. For any other path, the decision above it applies.
A list gives one place several decisions. Each applies on its own:
  • A recursive command is judged for each file it reaches. With cp: {decision: deny, paths: ["/data/src/secret/*"]}, cp -r /data/src /data/out is refused when it reaches /data/src/secret/key.pem.
  • Ask and deny leave the paths visible.

Lines, not file calls

A tree judges the lines a session runs. A file call outside a line, such as the agent’s read tool or session.vfs.read, is not judged by any tree. To close a path to every entry point, hide it.

A CLI that reaches a service

A hide stops file paths, and a CLI such as gh reaches its service without a path. So under a profile that hides any path, such a CLI stays off until the tree names it with an allow. "*": allow alone does not turn it on.

Ask with a reason

Changing an entry’s decision, reason or paths makes its lines ask again.

In one mount

A mount can carry its own tree. It applies to a line that works inside the mount: its working directory or a path it names is under the mount.
Mirage judges the profile’s tree and the mount’s tree separately, and the strictest result wins. A mount’s tree can only tighten.

Names

  • Write an option in any spelling the command declares: -r, -R or --recursive for rm. A subcommand takes its aliases too, such as ls for gh pr list.
  • Write each option as its own key. -rf is refused; write -r and -f.
  • Quote a key that YAML would not read as a string: "*", "5", "true".
Mirage checks every name when it loads the profile, and refuses a tree it cannot read one way: A misspelt operand is not caught. operands: {mian: deny} loads and never matches.

What a tree cannot say

  • Allow a command only with an option. Options only tighten, so git: {rm: {"*": deny, --cached: allow}} still refuses git rm --cached notes.txt. Deny the options you do not want instead, as in Only these options.
  • Keep a path from file calls. A tree judges lines only. Use paths.hide, as in Lines, not file calls.

Hide and show

  • paths.hide makes a path look absent. paths.show reopens a deeper path.
  • paths.hide takes absolute paths or name patterns such as *.pem; paths.show takes absolute paths only. * can cross /.
  • A hidden path is gone everywhere: from command output and counts, from links into it, from git history, and from what a checkout touches.
  • Moving a folder that holds a hidden path is refused.
Use Explain to check a rule before running a line.