Mirage · Unified Virtual Filesystem for AI Agents

The shell is how agents act on the workspace. execute() parses a bash-style command, looks up the target session, resolves mounts, runs the executor, applies I/O side effects, and records history.

`execute()`

Python
TypeScript
CLI

async def execute(
    self,
    command: str,
    session_id: str = DEFAULT_SESSION_ID,
    stdin: AsyncIterator[bytes] | bytes | None = None,
    provision: bool = False,
    agent_id: str = DEFAULT_AGENT_ID,
    native: bool | None = None,
    cwd: str | None = None,
    env: dict[str, str] | None = None,
    cancel: asyncio.Event | None = None,
) -> IOResult:
    ...

interface ExecuteOptions {
  stdin?: ByteSource | null
  provision?: boolean
  sessionId?: string
  agentId?: string
  native?: boolean
  signal?: AbortSignal
  noHistory?: boolean
  cwd?: string
  env?: Record<string, string>
}

async execute(command: string, options?: ExecuteOptions): Promise<ExecuteResult>

mirage execute --workspace demo --command "ls /data"
mirage execute --workspace demo --session agent-1 --command "pwd"

Per-call cwd / env / cancel are SDK-only as named flags. From the CLI, use bash subshell syntax inside the command string for per-call scoping (see below) and mirage job cancel to stop background work.

Per-call overrides: `cwd`, `env`

Providing cwd or env runs the command in an ephemeral session clone, like a bash subshell (cd /data && cmd). Mutations like cd or export inside the call do NOT persist back to the workspace’s session. To change persistent state, run the command without these options.

Python
TypeScript
CLI

# Persistent mutation (no options): like `cd /data; cmd`
await ws.execute("cd /data")
await ws.execute("ls")  # sees /data

# One-shot subshell (with cwd): like `(cd /data && cmd)`
await ws.execute("ls", cwd="/data")
# ws.cwd is unchanged; mutations inside don't leak

// Persistent mutation
await ws.execute("cd /data")
await ws.execute("ls")  // sees /data

// One-shot subshell
await ws.execute("ls", { cwd: "/data" })
// ws.cwd is unchanged; mutations inside don't leak

# Use a real bash subshell inside the command string
mirage execute -w demo -c "(cd /data && ls)"
mirage execute -w demo -c "(export FOO=bar; printenv FOO)"

The CLI doesn’t have --cwd / --env flags, but bash subshell syntax (cd ... && cmd) and (export FOO=bar; cmd) give the same per-call isolation. Mutations inside the parens don’t leak.

This makes per-call overrides safe under concurrent calls on the same session. Two parallel execute() calls with different cwd see their own cwd without cross-contamination, even on the same session.

Mid-flight cancellation: `cancel` / `signal`

Both bindings support cooperative cancellation observed at recursion boundaries (LIST, PIPELINE, FOR/WHILE/UNTIL iterations, COMMAND, subshells, command substitution) and inside sleep. On cancel, the call raises an abort error.

Python
TypeScript
CLI

import asyncio
from mirage.workspace.abort import MirageAbortError

cancel = asyncio.Event()

async def trigger():
    await asyncio.sleep(0.1)
    cancel.set()

asyncio.create_task(trigger())
try:
    await ws.execute("sleep 5", cancel=cancel)
except MirageAbortError:
    print("aborted")

try {
  await ws.execute("sleep 5", { signal: AbortSignal.timeout(100) })
} catch (e) {
  if (e instanceof DOMException && e.name === "AbortError") {
    console.log("aborted")
  }
}

# Background the job, then cancel it
JOB_ID=$(mirage execute -w demo -c "sleep 60" --bg)
mirage job cancel "$JOB_ID"

Per-call timeout is not a CLI flag yet. Use --bg to get a job id and mirage job cancel to terminate.

Three Scopes for State

Need	API	Bash equivalent
One isolated command	`execute(cmd, cwd=..., env=...)`	`(cd /data && cmd)`
Many isolated commands sharing scoped state	`session_id=...` (Py) / `sessionId` (TS)	a separate terminal
Persistent shell mutations	run without options	`cd /data; cmd`

Agent Pattern

Agent harnesses commonly fan out tool calls in parallel, each with its own cwd/env/cancel. The clone semantics make this race-free without per-call boilerplate.

Python
TypeScript

async def tool_call(cmd: str, cwd: str, env: dict[str, str], timeout: float):
    cancel = asyncio.Event()
    asyncio.get_event_loop().call_later(timeout, cancel.set)
    return await ws.execute(cmd, cwd=cwd, env=env, cancel=cancel)

results = await asyncio.gather(
    tool_call("ls", "/data", {"DEBUG": "1"}, 5.0),
    tool_call("grep foo *.log", "/logs", {"DEBUG": "1"}, 5.0),
)

async function toolCall(
  cmd: string,
  cwd: string,
  env: Record<string, string>,
  timeoutMs: number,
) {
  return ws.execute(cmd, { cwd, env, signal: AbortSignal.timeout(timeoutMs) })
}

const results = await Promise.all([
  toolCall("ls", "/data", { DEBUG: "1" }, 5000),
  toolCall("grep foo *.log", "/logs", { DEBUG: "1" }, 5000),
])

Getting Started

Learn

Help

Setup

Shell

`execute()`

Per-call overrides: `cwd`, `env`

Mid-flight cancellation: `cancel` / `signal`

Three Scopes for State

Agent Pattern

Getting Started

Learn

Help

Setup

Documentation Index

​execute()

​Per-call overrides: cwd, env

​Mid-flight cancellation: cancel / signal

​Three Scopes for State

​Agent Pattern

`execute()`

Per-call overrides: `cwd`, `env`

Mid-flight cancellation: `cancel` / `signal`

Three Scopes for State

Agent Pattern