workspace.yaml
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
processesscopes aresession(the default) orworkspace.maxis 128 by default; past it a new process fails withResource temporarily unavailable.- A profile’s
processesoverrides the workspace’s field by field. Itsnetworkcan 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
- Mirage reads the line with the command’s own grammar, so
rm -rf,rm -frandrm --recursive --forceare the same line. - 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.
- The options on the line, and their values, can only tighten that result:
denybeatsask, andaskbeatsallow.
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. commandsdoes not cover executed paths, direct VFS calls or MCP file tools. Limit file access withmountsandpaths.
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 mainruns andgit checkout devis refused. - An operand entry can hold options and a further
operandsfor the next word. Withmerge: {operands: {"5": {--admin: deny}}},gh pr merge 5 --adminis refused andgh pr merge 6 --adminruns. operandsgoes on a command that has no subcommands.
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 withpaths 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/outis 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’sread 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 asgh 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,-Ror--recursiveforrm. A subcommand takes its aliases too, such aslsforgh pr list. - Write each option as its own key.
-rfis refused; write-rand-f. - Quote a key that YAML would not read as a string:
"*","5","true".
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 refusesgit 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.hidemakes a path look absent.paths.showreopens a deeper path.paths.hidetakes absolute paths or name patterns such as*.pem;paths.showtakes 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.