Policies

A policy overrides only the hooks it needs. Each hook returns an answer, or None for no opinion. Pass policies to the workspace, or add and remove them later:

ws = Workspace(mounts, policies=[NoForcePush()])
ws.policies.add(reports)
ws.policies.remove(reports)

const ws = new Workspace(mounts, { policies: [noForcePush] })
ws.policies.add(reports)
ws.policies.remove(reports)

Hooks come in two groups. TypeScript spells them in camelCase (preCommand, ctx.sessionId).

Shell hooks

These fire when an agent runs a line: ws.shell, session.shell, the shell, ls and grep tools, mirage shell, HTTP /shell, RPC shell and SSH.

Hook	Fires	Reads	May answer	Explain asks it
`pre_command`	before each command	`command`, `argv`, `paths`, `operands`, `program`, `cwd`, `session_id`	Deny, Ask	yes
`pre_execute`	once per line, before it runs	`line`, `commands`, `cwd`, `env`, `session_id`	Deny, Route	yes
`post_execute`	after each line	`producer`, `exit_code`	Limit	no
`pre_session`	before each env write (`export`, `X=1`)	`verb`, `key`, `value`, `session_id`	Deny	no

Every command on a line passes pre_command before any of them runs, so a line refused whole never runs halfway.

pre_command

from mirage.policy import CommandContext, Deny, Policy

class NoForcePush(Policy):
    async def pre_command(self, ctx: CommandContext) -> Deny | None:
        if ctx.command == "git" and ctx.argv[:1] == ("push",) and "--force" in ctx.argv:
            return Deny("force pushes go through an operator")
        return None

const noForcePush: Policy = {
  preCommand(ctx) {
    const force = ctx.command === 'git' && ctx.argv[0] === 'push' && ctx.argv.includes('--force')
    return force ? { kind: 'deny', reason: 'force pushes go through an operator' } : null
  },
}

git push --force origin main gets git: Permission denied, exit 126.

pre_execute

from mirage.policy import Policy, Route
from mirage.runtime.routing import RouteContext

class JobsInDocker(Policy):
    async def pre_execute(self, ctx: RouteContext) -> Route | None:
        if any(p.startswith("/jobs/") for c in ctx.commands for p in c.paths):
            return Route("docker")
        return None

const jobsInDocker: Policy = {
  preExecute(ctx) {
    const jobs = ctx.commands.some((c) => c.paths.some((p) => p.startsWith('/jobs/')))
    return jobs ? { kind: 'route', runtime: 'docker' } : null
  },
}

python3 /jobs/train.py runs on the workspace’s docker runtime. See Route policy for runtimes.

post_execute

from mirage import Limit
from mirage.policy import ExecuteResultContext, Policy

class FirstHundredLines(Policy):
    async def post_execute(self, ctx: ExecuteResultContext) -> Limit:
        return Limit(max_lines=100)

const firstHundredLines: Policy = {
  postExecute() {
    return new Limit({ maxLines: 100 })
  },
}

A longer output stops at 100 lines, and stderr says output truncated at limit (100 lines); ....

pre_session

from mirage.policy import Deny, Policy, SessionContext

class NoCredentials(Policy):
    async def pre_session(self, ctx: SessionContext) -> Deny | None:
        if ctx.key.startswith("AWS_"):
            return Deny("credentials are set by the operator")
        return None

const noCredentials: Policy = {
  preSession(ctx) {
    return ctx.key.startsWith('AWS_')
      ? { kind: 'deny', reason: 'credentials are set by the operator' }
      : null
  },
}

export AWS_SECRET=x gets AWS_SECRET: permission denied, exit 1.

VFS hooks

These fire on every VFS call: session.vfs, the read, write, edit and glob tools, mirage vfs, HTTP /vfs/<call>, RPC vfs/<call>, FUSE, FSKit and SFTP. pre_vfs also fires for every file a shell command reads or writes.

Hook	Fires	Reads	May answer	Explain asks it
`pre_vfs`	before each VFS call, and each file a command touches	`op`, `path`, `write`, `create`, `session_id`	Deny, Ask	for a VFS call, not inside a line
`post_vfs`	after each VFS call	`op`, `path`, `result`	Deny, Limit	no

pre_vfs fires thousands of times under one grep -r, so keep it cheap. An Ask from it reaches a host only from session.vfs or a file tool; inside a line it refuses.

pre_vfs

from mirage.policy import Deny, Policy, VfsContext

class ReadOnlyReports(Policy):
    async def pre_vfs(self, ctx: VfsContext) -> Deny | None:
        if ctx.write and ctx.path.virtual.startswith("/reports/"):
            return Deny("reports are read-only")
        return None

const readOnlyReports: Policy = {
  preVfs(ctx) {
    return ctx.write && ctx.path.virtual.startsWith('/reports/')
      ? { kind: 'deny', reason: 'reports are read-only' }
      : null
  },
}

Every command gets its own error, exit 1:

$ echo x > /reports/q3.md
/reports/q3.md: Permission denied
$ cp notes.md /reports/
cp: cannot create regular file '/reports/notes.md': Permission denied

session.vfs.write("/reports/q3.md", ...) raises EACCES.

post_vfs

from mirage import Limit
from mirage.policy import Policy, VfsResultContext

class SmallReads(Policy):
    async def post_vfs(self, ctx: VfsResultContext) -> Limit | None:
        if ctx.op == "read":
            return Limit(max_bytes=1_000_000)
        return None

const smallReads: Policy = {
  postVfs(ctx) {
    return ctx.op === 'read' ? new Limit({ maxBytes: 1_000_000 }) : null
  },
}

session.vfs.read returns at most the first 1 MB. post_vfs does not see the reads inside a command, so cat is not cut; bound a line with post_execute.

Answers

Return	The agent gets
`None`	nothing changes
`Deny(reason)`	`rm: Permission denied`, exit 126; from a VFS hook, the command’s own error or `EACCES`
`Deny(reason, DenyScope.OPERAND, path=p)`	the command’s own error for `p`: `cat: /data/k: Permission denied`, exit 1; the rest of the line still runs
`Ask(reason)`	`cp: Permission denied`, exit 126, until a host answers; see Asks
`Route(runtime)`	the line runs on that runtime
`Limit(max_lines=, max_bytes=)`	the output cut at the bound, with a notice on stderr; with `on_exceed=OnExceed.ERROR`, no output and exit 1

TypeScript returns { kind: 'deny', reason }, with scope: 'operand', path for an operand, { kind: 'ask', reason }, { kind: 'route', runtime } and new Limit({ maxLines }). A hook that raises refuses too. The reason never goes to stderr. It is on the result’s refusal:

r = await ws.shell("git push --force origin main")
r.refusal
# Refusal(kind='deny', reason='force pushes go through an operator', policy='NoForcePush', scope='command', ask_id=None)

The agent tools add one line to their text: policy denied: <reason>, or requires approval: <reason> (ask <id>).

When policies disagree

Any Deny beats any Ask, so answering an ask never reopens a refusal.
The first Deny speaks. Built-ins come first, then the session’s profile, then policies=, then add().
Limits merge to the tightest value of each field.
Two Routes to different runtimes refuse the line.

Which door enforces what

A line fires every hook; a VFS call fires only the VFS hooks. So a profile rule that names a command holds only on a line, and a rule that names only paths holds on both. session.tools.names() lists only the tools the session’s profile leaves it, and MCP, RPC and the agent adapters offer exactly those.

Examples

policy.py and policy.ts run a coded policy beside a profile’s policy: script. Their output is pinned in CI.

Getting Started

Access

Policy

Learn

Help

VFS

CLIs

Runtimes

Shell hooks

pre_command

pre_execute

post_execute

pre_session

VFS hooks

pre_vfs

post_vfs

Answers

When policies disagree

Which door enforces what

Examples

​Shell hooks

​pre_command

​pre_execute

​post_execute

​pre_session

​VFS hooks

​pre_vfs

​post_vfs

​Answers

​When policies disagree

​Which door enforces what

​Examples

Shell hooks

pre_command

pre_execute

post_execute

pre_session

VFS hooks

pre_vfs

post_vfs

Answers

When policies disagree

Which door enforces what

Examples