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.
Record<string, MountSpec>
required
The VFS at each path, such as { '/': new RAMVFS(), '/s3': new S3VFS(config) }.
MountMode
default:"MountMode.READ"
The mode a mount gets when it sets none: READ, WRITE or EXEC.
Record<string, SessionProfile>
Named profiles a session can be created under.
string
The profile a session gets when it names none.
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.
string
The workspace’s id, generated when unset.
string
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 ownsStore: true.
See Workspace configuration for snake_case 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 sessionId, creating it if the id is new.
  • profile, mounts and permissions apply only when the session is created. Passing them for an existing session throws.
  • permissions adds a command tree, hides and narrower mount modes for this session. The stricter of it and the profile wins, so it cannot allow what the profile refuses. It cannot add a policy.
  • ws.createSession(...) is the sync form. It returns a SessionState, not a Session.
  • setProfile(name, profile) adds or replaces a named profile. An invalid profile throws PolicyError and changes nothing.
  • Running sessions keep their old rules until you call setSessionProfile.
  • setSessionProfile(sessionId, profile) takes a profile name, null (the workspace default) or an inline profile object. 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. An inline profile 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 resolves once they have ended; each rejects with an AbortError. 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, or an object key with s3; source can also be the bytes. With no target, snapshot returns the tar’s bytes; with one, its size.
  • While it captures, new lines and file writes wait. Running ones get 30 seconds to end, else it rejects with an EBUSY error. A path target streams disk mount files rather than holding them 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, the default, 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.
string
SessionState
The session’s record, as returned by ws.listSessions.
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 (the default), it collects the execution’s output and returns an ExecuteResult. A non-zero exit is a result, not an exception. ws.shell has the same streaming option and accepts sessionId to select the session.
Uint8Array | AsyncIterable<Uint8Array>
The line’s stdin. An async iterable streams it.
string
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.
Record<string, string>
Variables for this line only. Like cwd, they run the line in a subshell of its own.
AbortSignal
Aborting it stops the line, which throws an AbortError.
boolean
default:"true"
false keeps the line out of history.
string
Run the commands this workspace machine captures on it, by name, instead of where routing puts them. Throws for a name the workspace does not have.
JobConsole
Write the line’s output to this console as each statement finishes. Cannot be combined with stream: true. The result then carries the exit code with empty stdout and stderr. The caller calls finish() on the console.
stream: true returns a ShellExecution. Read execution.events (stdout and stderr chunks, in order), then await execution.wait() for the exit code.
  • Read the events before awaiting wait(). A full queue (64 KiB, set by the workspace I/O settings) blocks the line.
  • Call await execution.close() in finally, so stopping early cancels the line. cancel() requests cancellation; wait() then rejects with AbortError.
  • await execution.collect(callback) gives the full result and calls callback for each chunk.
  • A policy with postExecute holds output until the line finishes.
In this example, sendBytes 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 Uint8Array. A failure throws an Error whose code is the POSIX name, as Node’s fs does: ENOENT, EACCES, EROFS. 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 isError, never a throw. 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. readMedia(path) answers an image or a PDF as media instead of numbered text, for adapters that hand media to the model. @struktoai/mirage-core/workspace/tools/tool_descriptions (needs pnpm add @struktoai/mirage-core) has each tool’s description and JSON schema to hand the model, and the agent adapters wire the tools into each framework. new MirageToolOperations(session, false), from @struktoai/mirage-core/workspace/tools/tool_operations, is a table without the read guard.