Skip to main content
Policy decides what an agent may do in the virtual terminal: the commands it runs, the files it reads and writes, and the connections it opens. It runs inside the shell and the filesystem, so it judges each command after expansion and each file a command reaches, however the agent connects.

Example

A review agent that reads a repository, never sees its secrets and deletes nothing:
workspace.yaml
A session under reviewer, such as ws.session("agent", profile="reviewer"):
The host still writes /repo; the profile narrows only that session. Session Profiles lists every key, and Command rules shows how to write a rule for a subcommand, an option or an operand.

Three ways to write policy

Methods

A class or a script answers at any of these methods. A pre_ method runs before the action; a post_ method runs after it, with what came back, and never undoes what ran. None is no opinion. A Deny refuses, an Ask waits for the host’s approval, a Route picks the machine and a Limit caps the output or the connection. See Answers.

Order

Built-in checks answer first: mount modes, path rules, the workspace’s network lists and its route_policy. Then the session’s profile rules and scripts, then the workspace’s policies in the order they were added. The first Deny wins, and an Ask never reopens a Deny, so no policy can allow what another refuses. See When answers disagree.

Why not a tool-call check

A harness’s tool-call check, such as Claude Code’s PreToolUse or an SDK’s can_use_tool, sees one tool call: a tool name and a string such as cat $(ls /data | head -1). A Mirage policy sees what that string runs.

Next steps

Policies

Write a policy class: its methods, context and answers.

Scripts

Write a policy as a sandboxed program a profile names.

Explain

What the agent reads when refused, and how it asks first.

Route Machine

Choose the machine that runs each line.

Route Network

Send a connection to one address to another.