Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt

Use this file to discover all available pages before exploring further.

The Workspace is the shared kernel inside Mirage’s Arm. It is the concrete Python object that holds the resources shared across mounts, commands, and sessions. Technically, Workspace owns the global coordination layer of Mirage: mounts, cache, command registry, job tracking, execution history, and session lifecycle.

​
Unix Analogy

Unix kernelMirage Workspace
VFS mount tableMountRegistry
Page cacheFile cache and index cache
Process tableJob table
System call dispatchCommand registry
Shell hostSession manager plus executor
Just as the kernel is shared across all shells and processes, the Workspace is shared across all sessions. Multiple sessions read from the same mounts, share the same cache, and have their jobs recorded in the same job table.

​
What Workspace Owns

  • Mount registry - prefix-based routing of virtual paths to resources
  • Cache - shared file and index cache used across commands and sessions
  • Command registry - command and op lookup through mounted resources
  • Job table - background job tracking
  • Execution history - recorded command runs and I/O metadata
  • Observer stream - read-only session traces exposed at /.sessions
  • Session manager - creation, lookup, and closing of sessions

​
What Workspace Coordinates

  • execute() parses a shell command, runs it against the right mounts, and returns an IOResult
  • dispatch() routes low-level ops to the right mounted resource
  • sync() flushes dirty data back to resources when the sync policy requires it
  • close() shuts down FUSE state, background tasks, and cache state

​
Session Lifecycle Through Workspace

  • create_session() creates a new session with its own cwd and env
  • get_session() retrieves a session by id
  • list_sessions() lists all active sessions
  • close_session() closes one session
  • close_all_sessions() closes every non-default session
Session details live on the separate Sessions page.

​
What Workspace Does Not Own

  • Per-session mutable state - cwd, env, functions, and last exit code live on Session
  • Mount semantics - prefix binding and access policy belong to Mounts
  • Shell syntax - parsing, expansion, and control flow belong to the Shell

​
Common Shape

ws = Workspace({
    "/": (RAMResource(), MountMode.WRITE),
    "/s3": (s3, MountMode.READ),
})
This is the common split: writable scratch space at /, read-only remote data at named prefixes.

​
execute()

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,
):
execute() is the main entrypoint into the kernel. It parses the command, looks up the target session, resolves mounts, runs the shell executor, applies I/O side effects, and records history.

​
Persistence: save, load, copy

A Workspace can be serialized to a tar archive and reloaded later, or copied in-process for speculative execution / parallel agent forks: 
ws.snapshot("snap.tar")                        # full state to disk
new_ws = Workspace.load("snap.tar",            # fresh Workspace from snapshot
                        resources={"/s3": fresh_s3})
forked = ws.copy()                             # in-process deep copy
The snapshot captures mounts (with resource content for RAM/Disk/Redis), cache entries, sessions, dirty inodes, history, and finished jobs. Cloud credentials are redacted at save time and must be re-supplied via resources=... at load time. The same machinery powers OpenAI Agents sandbox checkpoints (persist_workspace / hydrate_workspace). See Snapshot for the format, override rules, copy-vs-save divergence, and OpenAI Agents integration.
  • Mounts explain prefix routing and access modes.
  • Sessions explain per-terminal state.
  • Snapshot covers save/load/copy and the OpenAI Agents sandbox checkpoint integration.
  • Arm explains the higher-level metaphor.