Skip to main content
A policy is a Python or TypeScript class that controls what the agent does. Before an action runs, and again once it returns, the policy gets the full context: the line, each command with its expanded arguments, the paths it touches, the session, and what came back. It then lets the action through (None), refuses it, asks a host, caps its output, or picks the machine that runs it.

Lifecycle

A policy implements any of nine methods: four pairs, plus pre_workspace on a server. A pre_ method runs before an action; a post_ method runs after it, with the same context and what came back. A post_ method never undoes what ran: its Deny or Ask holds back what came back. TypeScript spells each method in camelCase (preExecute). Every entry point reaches the same methods:

Context

Each method gets one argument, ctx: what its method is about, on that method’s page, plus the session. TypeScript spells the fields in camelCase (ctx.sessionId). Every ctx carries: A method only reads. A write it makes through Mirage is refused (EROFS for a file, EACCES for a variable), and its reads are not judged again. The session’s history is /.bash_history, which a method reads through ctx.vfs like any file.

What the agent controls

Most of a ctx comes from what the agent did, so a policy reads it as a claim to check, not as a credential: The host sets session_id (caller.session.session_id too), profile, mounts, prefix and mode, and what vfs shows: the agent cannot change them from inside the session. Decide who may do what from those, and from a variable only when the workspace’s or the profile’s env sets it with readonly: true. session.is_readonly() is also true for a name the agent marked with readonly NAME itself. A policy written as a program, on monty or Python on wasm, gets the same ctx as JSON: see Scripts.

Variables

A variable write reaches no method: a variable does nothing until a command, a file call or a connection uses it, and each of those methods reads the session (ctx.session, and a command’s env), so a rule about a value goes in the method that uses it.

Answers

TypeScript returns { kind: 'deny', reason }, with path for a path, { kind: 'ask', reason }, { kind: 'route', machine } and new Limit({ maxLines }). A method that raises refuses too. What the agent reads for each is on Explain.

Asks

An Ask records a question in the workspace’s ledger:
  • With on_ask (onAsk), an inline allow answer continues the current request; a deny answer refuses it.
  • Without an inline answer, including when the callback returns no decision, the request returns pending. The host records a decision in the ledger, allowing the caller to retry.
Ledger answers apply as follows:
  • allow, scope once (default): the retry runs and spends it.
  • allow, scope session: everything the ask covers, for the rest of that session.
  • deny: the retry is refused; running it again asks again.
A host answers through ws.decisions, mirage workspace allow or POST /asks/{ask_id}. An Ask from a post_ method comes after the action ran, so nothing is undone: what came back is held, and the approved retry runs it again.

When answers disagree

  • Any Deny beats any Ask, so answering an ask never reopens a refusal.
  • The first Deny speaks. The built-ins come first, then the session’s profile, then its script, then policies=, then add().
  • Every Ask is put to the host, and the action runs once all are approved.
  • Limits merge to the tightest value of each field.
  • Two Routes to different machines refuse the line.
  • A policy may give several answers at once, a tuple in Python or an array in TypeScript; each counts as if a policy of its own gave it.

Examples

policy.py and policy.ts run a profile’s scripts.