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.

A mount is how Mirage attaches one resource to one visible prefix. If Eyes are how agents see, a mount is the attachment point that puts a new region of the world within reach of the Arm.

​
Resource Versus Mount

ConceptRole
ResourceKnows how to read and write one external system
MountBinds 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. 
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 are allowed to do at a prefix.
ModeBehavior
READRead only. Write commands are blocked.
WRITERead and write. Standard filesystem operations are enabled.
EXECRead, write, and execute.

​
Examples

​
One Global Default

ws = Workspace({"/s3": s3}, mode=MountMode.READ)
Every mounted resource inherits READ unless a mount overrides it.

​
Per-Mount Control

ws = Workspace({
    "/s3": (s3, MountMode.READ),
    "/scratch": (RAMResource(), MountMode.WRITE),
})
This is the common pattern: remote data stays read only, scratch space stays writable.
  • Workspace owns the mount registry.
  • Sessions decide where commands run from.
  • Eyes explain why mounted prefixes are the right representation layer.