Workspace
The VFS at each path, such as
{"/": RAMVFS(), "/s3": S3VFS(config)}. Each value is a VFS, (vfs, mode), (vfs, mode, limits) or Mount(...).Named profiles a session can be created under.
Policies every line passes through.
Resolves an approval request (ask) while the line waits. Without a handler, asks are recorded in
ws.decisions.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.mode to READ; YAML defaults it to write.
Workspace methods
Expand one for its signature and an example.
ws.session
ws.session
Session for session_id, creating it if the id is new.profile,mountsandpermissionsapply only when the session is created. Passing them for an existing session raisesValueError.permissionsadds 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 aSessionState, not aSession.
ws.set_profile, ws.set_session_profile
ws.set_profile, ws.set_session_profile
set_profile(name, profile)adds or replaces a named profile. A profile no session could run under raisesPolicyErrorand 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:
whoamiprints it (uid 1000). A session with no profile isroot. A profile document passed directly has uid 1000 and no name.
ws.list_sessions, ws.close_session
ws.list_sessions, ws.close_session
ws.cancel, ws.kill
ws.cancel, ws.kill
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.ws.snapshot, Workspace.load
ws.snapshot, Workspace.load
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.
ws.copy
ws.copy
ws.decisions
ws.decisions
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.ws.close
ws.close
Session
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.
The session’s record, as returned by
ws.list_sessions.The workspace’s asks ledger, which records pending approval requests for this session.
session.shell
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.
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.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.Stream the output
Stream the output
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 withIOConfig) blocks the line. - Use
async with execution:(orawait execution.aclose()) so stopping early cancels the line.cancel()stops it, andwait()then raisesMirageAbortError. await execution.collect(on_event=callback)returns the full result and awaitscallbackfor each event.- A policy with
post_executeholds output until the line finishes.
send_bytes is the application’s async output sink:More session calls
session.glob
session.glob
session.explain
session.explain
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 arebytes. 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
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.