Skip to main content
Call these when your agent runs in the same process as the workspace. The server, MCP, SSH and the CLI all call them underneath.

Workspace

One virtual terminal over the VFS mounted at each path.
dict[str, VFSMount]
required
The VFS at each path, such as {"/": RAMVFS(), "/s3": S3VFS(config)}. Each value is a VFS, (vfs, mode), (vfs, mode, limits) or Mount(...).
MountMode
default:"MountMode.READ"
The mode a mount gets when it sets none: READ, WRITE or EXEC.
dict[str, SessionProfile]
Named profiles a session can be created under.
str
The profile a session gets when it names none.
list[Policy]
Policies every line passes through.
AskHandler
Resolves an approval request (ask) while the line waits. Without a handler, asks are recorded in ws.decisions.
str
The workspace’s id, generated when unset.
str
The default session’s id.
WorkspaceStateStore
Where the workspace keeps its state: symlinks and file attributes, command logs, sessions and background jobs. In memory when unset. A store passed in is borrowed: close it after ws.close(), or pass owns_store=True.
See Workspace configuration for YAML settings. Direct SDK construction defaults mode to READ; YAML defaults it to write.
Set the per-queue capacity when creating the workspace:
Every process that builds the workspace on one Redis store, under the same ids, shares its sessions and background jobs:

Workspace methods

Expand one for its signature and an example.
Returns the Session for session_id, creating it if the id is new.
  • profile, mounts and permissions apply only when the session is created. Passing them for an existing session raises ValueError.
  • permissions adds rules for this session only, on top of its profile: a command tree, hides and weaker mount modes. The stricter of it and the profile wins, so it cannot allow what the profile refuses. It cannot add a policy.
  • ws.create_session(...) is the sync form. It returns a SessionState, not a Session.
  • set_profile(name, profile) adds or replaces a named profile. A profile no session could run under raises PolicyError and changes nothing.
  • Running sessions keep their old rules until you call set_session_profile.
  • set_session_profile(session_id, profile) takes a profile name, None (the workspace default) or a profile document. The session keeps its working directory, variables and history.
  • The profile name is the session’s user: whoami prints it (uid 1000). A session with no profile is root. A profile document passed directly has uid 1000 and no name.
List the sessions, or close one: its lines are cancelled and its jobs end. The default session cannot be closed.
Stop a session’s work, or every session’s with no id, and leave the sessions open. cancel cancels the running and queued lines, whichever way they came in, and returns once they have ended; each ends with MirageAbortError. kill kills the background jobs (cmd &) and the programs machines started. Each answers how many it stopped.
Save the workspace to a tar and rebuild it from one. target and source are a path, a file object, or an object key with s3=. snapshot returns the tar’s size in bytes.
  • While it captures, new lines and file writes wait. Running ones get 30 seconds to end, else it raises OSError (EBUSY). Disk mount files are streamed, never held whole.
  • The tar keeps the profiles, the command limits and each store’s capacity. Each session loads back under the restrictions it ran with.
  • An override brings its own capacity, or none.
  • The scratch root, the RAM root added when nothing is mounted at /, comes back as the scratch root, an override for it included.
A deep copy, without a tar in between.
The asks waiting for a host. Each one belongs to the session that ran the line: pending() lists every session’s, pending("agent") one session’s, and an answer never reaches another session. outcome is Outcome.ALLOW or Outcome.DENY. Scope.ONCE resolves the pending ask for this line, allowing its retry to run or be refused; Scope.SESSION allows every line the rule covers for the rest of that session.
Stops its jobs and closes its mounts. Sessions and history stay in the workspace’s store.

Session

One session’s handle, from ws.session. Every call on it runs under the session’s profile, working directory and environment. ws.shell, ws.glob, ws.vfs and ws.tools are the same calls as the workspace’s default session.
str
SessionState
The session’s record, as returned by ws.list_sessions.
Files
The file API, below.
MirageToolOperations
The agent tools, below.
Decisions
The workspace’s asks ledger, which records pending approval requests for this session.

session.shell

Runs a shell line as the session. With stream=False, it collects the execution’s output and returns an IOResult. A non-zero exit is a result, not an exception. ws.shell has the same streaming option and accepts session_id to select the session.
bytes | AsyncIterator[bytes]
The line’s stdin. An async iterator streams it.
str
A working directory for this line only. The line runs in a subshell of its own, beside the session’s other lines rather than after them: a cd in it does not leak, and its jobs are its own.
dict[str, str]
Variables for this line only. Like cwd, they run the line in a subshell of its own.
asyncio.Event
Setting it stops the line and raises MirageAbortError.
bool
default:"True"
False keeps the line out of history.
str
Run the commands this workspace machine captures on it, by name, instead of where routing puts them. Raises ValueError for a name the workspace does not have.
await session.shell(line, stream=True) returns a running ShellExecution. Read execution.events (ordered stdout and stderr chunks, each with stream and data bytes), then await execution.wait() for the final IOResult: the exit code and refusal, with empty output fields.
  • Read the events before awaiting wait(). A full queue (64 KiB by default, set with IOConfig) blocks the line.
  • Use async with execution: (or await execution.aclose()) so stopping early cancels the line. cancel() stops it, and wait() then raises MirageAbortError.
  • await execution.collect(on_event=callback) returns the full result and awaits callback for each event.
  • A policy with post_execute holds output until the line finishes.
In this example, send_bytes is the application’s async output sink:

More session calls

The paths a pattern matches, as the session sees them.
What session.shell or a session.vfs call would do, without running it: a line’s verdict and parse tree, a VFS call’s verdict and error, each with every policy’s answer. See Explain.

session.vfs

The file API, run as the session. Paths are absolute, bytes are bytes. A missing path raises FileNotFoundError and a refused one PermissionError. stat may answer from the mount’s listing index. Pass fresh=True to ask the service directly, for example after another client changed the file. Later calls then see the new answer. nofollow=True reports a trailing symlink itself.

session.tools

The seven agent tools, for a model rather than a program: every answer is text, and a failure is is_error, never an exception. call takes a tool’s name and its JSON input, the form an agent loop gets from the model. write and edit refuse a file the session has not read in full, or one that changed since it was read. Every caller of the session shares that record. names() is the tools the session’s profile leaves it, which MCP, RPC and the agent adapters offer: shell needs a command its commands lets run, ls and grep those commands, write and edit a mount the session may write. mirage.workspace.tools.tool_descriptions has each tool’s description and JSON schema to hand the model, and the agent adapters wire the tools into each framework. MirageToolOperations(session, stale_write_protection=False), from mirage.workspace.tools.tool_operations, turns the read guard off.