---
title: Workspace
description: The shared kernel inside Mirage's Arm. It owns mounts, cache, command registry, jobs, and execution history.
icon: server
---

The `Workspace` is the shared kernel inside Mirage's [Arm](/home/design/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 kernel | Mirage Workspace |
| ----------- | ---------------- |
| VFS mount table | `MountRegistry` |
| Page cache | File cache and index cache |
| Process table | Job table |
| System call dispatch | Command registry |
| Shell host | Session 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](/home/design/session) 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](/home/design/mount)
- **Shell syntax** - parsing, expansion, and control flow belong to the [Shell](/home/design/pipeline)

## Common Shape

```python
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()`

```python
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:

```python
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](/home/design/snapshot) for the format, override rules,
copy-vs-save divergence, and OpenAI Agents integration.

## Related

- [Mounts](/home/design/mount) explain prefix routing and access modes.
- [Sessions](/home/design/session) explain per-terminal state.
- [Snapshot](/home/design/snapshot) covers save/load/copy and the OpenAI Agents sandbox checkpoint integration.
- [Arm](/home/design/arm) explains the higher-level metaphor.
