Skip to main content
A policy can be a program instead of a class. A profile names programs for each method, and each program defines a function named for its method: it takes 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
Each program is in its method’s section below. A session under agent:
Each entry names its 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.
A profile in code takes the same block, with a ScriptSource for each program:

The program

  • Input. ctx is the function’s argument. The same JSON is in the MIRAGE_POLICY_CTX variable, and on wasi and pyodide also on stdin; monty has no sys.stdin.
  • Environment. The program starts in the session’s working directory. The session’s variables are in ctx["env"], not os.environ, which holds only MIRAGE_POLICY_CTX and the entry’s own env.
  • 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 print fails 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 the ctx 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. For cat 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. For cat 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 adds result, what the call returned. For the stat above:
A deny drops the result with EACCES; the call itself is not undone.

pre_network

Asked before each connection carries a byte, whoever opens it. For git 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. Its ctx holds no session:
no_disk.py
A deny answers the request with 403 and its reason. See Workspace.

Every ctx

Every ctx 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’s env 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
A session record and a snapshot keep the pointer, never the value it read. A source that cannot answer refuses the action, as a failed program does. 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 on wasi and pyodide, and the agent’s own programs, do not see them.
guard.py
A function may be sync or async and takes and returns plain data: strings, numbers, booleans, 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
With it as the session’s pre_command program:
The program reads the code as text, so it stops the usual calls, not every way Python can delete a file. A rule that must always hold belongs in a coded policy, which judges each file call itself.

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 as profile '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.