ctx as plain data and returns its answer as a dict. The methods and
what each answer does are the same as a coded policy’s.
Example
workspace.yaml
agent:
script and, optionally:
A method’s programs are asked in order, up to the first deny, and each answer
counts as if a policy of its own gave it. A method with no program is never
asked and costs nothing.
In code
In code
A profile in code takes the same block, with a
ScriptSource for each
program:The program
- Input.
ctxis the function’s argument. The same JSON is in theMIRAGE_POLICY_CTXvariable, and onwasiandpyodidealso on stdin; monty has nosys.stdin. - Environment. The program starts in the session’s working directory.
The session’s variables are in
ctx["env"], notos.environ, which holds onlyMIRAGE_POLICY_CTXand the entry’s ownenv. - Answer. What the function returns. On monty the function may be
async def, to await host functions. - stdout carries the answer back as JSON, so a stray
printfails the program. Write debug lines to stderr.
A deny or an ask without a
reason gets a default one. A program cannot
return a Limit; a coded policy can.
Methods
A program can answer at any of these. Each section below shows thectx it
gets.
A
post_ method gets its pre_ method’s ctx plus what came back. It
never undoes what ran: its deny or ask holds back what came back.
pre_execute
Asked once per line, before any of it runs. Forcat notes.txt | wc -l in
/data:
A command’s own
NAME=value prefix is in its entry’s env only: for
GPU=1 python3 train.py, only python3 has GPU. Words only the run can
expand ($X) are not resolved yet.
no_pipe_to_shell.py
post_execute
Asked once the line ends. It adds:
A deny drops the output: exit 126 and a refusal record.
pre_command
Asked before each command or CLI, nested ones included. Forcat notes.txt:
no_force_push.py
post_command
Asked after each command, once its output drained. It adds:
A deny sets its exit code to 126, so
&& and pipefail stop there. Output
already sent stays sent.
pre_vfs
Asked before each VFS call: a command’s file calls,session.vfs, a
runtime’s file API, FUSE and SFTP. cat notes.txt makes a stat, then a
read:
reports_read_only.py
post_vfs
Asked after each VFS call. It addsresult, what the call returned. For the
stat above:
EACCES; the call itself is not undone.
pre_network
Asked before each connection carries a byte, whoever opens it. Forgit clone https://github.com/strukto-ai/mirage /repo/mirage:
The URL, method and status are not there: under HTTPS only the program and
the server see them. To refuse a clone by its size, look the repository up
from the URL in
words: a program on monty has no network, so it asks a
host function, as the
coded example asks
GitHub’s API.
github_only.py
post_network
Asked once the connection is over, however it ended. It adds:ended is closed, refused (by a later policy), limit or error. A
program here observes, for a log or a running count, and returns
nothing.
pre_workspace
Only a server’s policy file asks it, before a create, clone or load builds anything or reads a secret. Itsctx
holds no session:
no_disk.py
Every ctx
Everyctx but pre_workspace’s also carries the session:
mounts lists the mount roots the session can see. The agent sets cwd,
env and what a command says; what the agent controls
says which fields a program can trust.
Variables
An entry’senv gives its program variables beside MIRAGE_POLICY_CTX, on
every runtime. A value is a string, or a pointer to a
credential source such as aws-sm or 1password,
read the first time the program runs and kept for the workspace’s life:
workspace.yaml
MIRAGE_POLICY_CTX cannot be set here.
Host functions
A program on monty can call functions the host hands the workspace, by name. They are passed in code, never in a document or over the server API, so a profile can call them but not add one. Programs onwasi and
pyodide, and the agent’s own programs, do not see them.
guard.py
None, lists and dicts. One that raises raises in the
program, which may catch it; uncaught, the program fails and the action is
refused. A function may take as long as it needs, within the program’s 10
seconds, and programs calling functions run side by side rather than one at
a time.
Files and the session
A program reads the workspace as the session it judges:open(),
os.listdir() and os.stat() go through the workspace, a hidden path does
not exist, and a write is refused (EROFS). Its own reads are not judged
again. So a program can judge a file by what is in it. This one refuses
rm, and a Python script whose code deletes files:
guard.py
pre_command program:
When a program fails
A program that defines no function for its method, exits non-zero, runs past 10 seconds, returns anything but an answer its method can give, or names a runtime that cannot run here refuses the action. The reason names the profile and what went wrong, such asprofile 'reviewer' policy exited 1, and the program’s stderr goes to the log. Failing open would let
through exactly what the policy is there to judge.
Where programs go
Runtimes
Each runtime is the policy’s own, built from the name and settings the
profile gives and never shared with the agent. Monty is the default, and it
must be installed:
mirage-ai[monty] in Python, @pydantic/monty in
TypeScript. Without it, a program on monty refuses every action it judges
and the refusal names the package to install. wasi needs a CPython WASI
build: its folder as config: {home: ...}, or in MIRAGE_WASI_HOME.
A program gets 10M of memory on monty and 128M on wasi and pyodide,
unless its runtime’s config names max_memory (null for no cap). A
program that needs more fails like any other.
Monty runs a program in about a millisecond. wasi starts CPython on every
run, 100 to 300 ms, so it suits the methods asked less often; pre_vfs,
asked for every file call from outside a line, is usually monty’s.