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.
83 lines
2.4 KiB
Plaintext
83 lines
2.4 KiB
Plaintext
---
|
|
title: Mounts
|
|
description: How resources attach to virtual prefixes and how access modes shape what agents can do.
|
|
icon: hard-drive
|
|
---
|
|
|
|
A mount is how Mirage attaches one resource to one visible prefix. If [Eyes](/home/design/eyes) are how agents see, a mount is the attachment point that puts a new region of the world within reach of the [Arm](/home/design/arm).
|
|
|
|
## Resource Versus Mount
|
|
|
|
| Concept | Role |
|
|
| ------- | ---- |
|
|
| Resource | Knows how to read and write one external system |
|
|
| Mount | Binds that resource to a prefix and access mode inside a `Workspace` |
|
|
|
|
The same resource type can be mounted more than once at different prefixes, with different access policies.
|
|
|
|
## Prefix Routing
|
|
|
|
Mirage resolves paths with longest-prefix match.
|
|
|
|
That means `/data/sub/file.txt` resolves to `/data/sub/` if both `/data/` and `/data/sub/` exist as mounts.
|
|
|
|
```python
|
|
reg.mount("/data/", p1, MountMode.WRITE)
|
|
reg.mount("/data/sub/", p2, MountMode.WRITE)
|
|
```
|
|
|
|
This lets Mirage combine broad mounts with narrower overrides.
|
|
|
|
## What A Mount Carries
|
|
|
|
Each mount bundles the pieces needed for dispatch at one prefix:
|
|
|
|
- a normalized prefix such as `/s3/`
|
|
- the resource instance
|
|
- an access mode
|
|
- resource-specific command registrations
|
|
- resource-specific VFS operation registrations
|
|
- optional cross-mount command handlers
|
|
|
|
In practice, this means Mirage can answer both questions at once:
|
|
|
|
- Which backend owns this path?
|
|
- Which command or filesystem operation should handle it?
|
|
|
|
## Mount Modes
|
|
|
|
Mount modes control what the [Hands](/home/design/hands) are allowed to do at a prefix.
|
|
|
|
| Mode | Behavior |
|
|
| ---- | -------- |
|
|
| `READ` | Read only. Write commands are blocked. |
|
|
| `WRITE` | Read and write. Standard filesystem operations are enabled. |
|
|
| `EXEC` | Read, write, and execute. |
|
|
|
|
## Examples
|
|
|
|
### One Global Default
|
|
|
|
```python
|
|
ws = Workspace({"/s3": s3}, mode=MountMode.READ)
|
|
```
|
|
|
|
Every mounted resource inherits `READ` unless a mount overrides it.
|
|
|
|
### Per-Mount Control
|
|
|
|
```python
|
|
ws = Workspace({
|
|
"/s3": (s3, MountMode.READ),
|
|
"/scratch": (RAMResource(), MountMode.WRITE),
|
|
})
|
|
```
|
|
|
|
This is the common pattern: remote data stays read only, scratch space stays writable.
|
|
|
|
## Related
|
|
|
|
- [Workspace](/home/design/workspace) owns the mount registry.
|
|
- [Sessions](/home/design/session) decide where commands run from.
|
|
- [Eyes](/home/design/eyes) explain why mounted prefixes are the right representation layer.
|