Zecheng Zhang
924ec49796
A unified virtual filesystem for AI agents. Mount S3, Google Drive, Slack, Gmail, GitHub, Linear, Notion, Postgres, MongoDB, SSH, and more behind one filesystem so agents read, write, and pipe across services with familiar shell commands. Ships Python (mirage-ai) and TypeScript (@struktoai/mirage-*) SDKs, a CLI, FUSE mounts, and adapters for OpenAI Agents SDK, Vercel AI SDK, LangChain deepagents, Pydantic AI, CAMEL, OpenHands, Mastra, Pi Coding Agent, plus FUSE-based integration with Claude Code and Codex. Apache 2.0 licensed.
119 lines
4.4 KiB
Plaintext
119 lines
4.4 KiB
Plaintext
---
|
|
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.
|