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 Mirage Mental Model

Mirage turns external systems into a virtual filesystem so agents and tools can use one consistent interface instead of resource-specific APIs.

​
The Pieces, In One Breath

  • Eyes, how agents see. Mounted resources expose external systems as paths.
  • Hands, how agents act. Read, write, search, transform, compose through byte streams.
  • Brain (the Agent), orchestrates. Decides which Hands to use, spends tokens reasoning, and owns what gets done.
  • Arm, Mirage’s reach. Extends the agent from the Brain into external systems. Expands into Workspace, Mounts, Sessions, and Shell.
  • Shell, the wiring inside the Arm. Turns a sentence like cat /s3/*.csv | grep error into coordinated eye-and-hand movement.
  • Fingers, the primitive gestures every backend implements: ops (read, readdir, stat, write, mkdir, unlink, rename) plus FUSE to expose them via POSIX. The fundamental infrastructure layer.
  • Gestures, named commands built on fingers. cat, grep, cp, jq, each is one coordinated motion the agent can name directly. When a gesture reaches across two resources (cp /s3/a /gdrive/b), it becomes a Handshake, two hands meeting. (Higher-level agent Skills, à la Anthropic Agent Skills, compose gestures and handshakes into complex workflows at the harness layer.)
  • Recall (the cache), what the Hands have already produced and the tokens the Brain has already spent, so the same work never happens twice. Split into Index Store and File Store.

​
Core Concepts

​
Arm

The Arm is Mirage’s reach, the connected limb that extends the agent from the Brain into external systems. It brings together Eyes, Hands, mounts, sessions, and shell execution into one coherent reach.

​
Workspace

A Workspace is the concrete Python object and shared kernel inside the Arm. It owns the global resources that stay shared across commands and sessions: mounts, cache, command registry, jobs, and execution history.

​
Resources and Mounts

A resource maps one external system into Mirage. A mount attaches that resource to a prefix such as /data, /s3, or /github. Resources and mounts are the substance of Mirage’s Eyes, and they are the regions of the world the Arm can reach into.
  • Examples: RAMResource() mounted at /data GitHubResource(...) mounted at /github
  • Deep dive: Mounts
  • Deep dive: Eyes

​
Sessions

A Session holds the mutable execution context for one terminal-like thread of work: current directory, environment variables, shell functions, and last exit code. The Arm is shared. Sessions are the postures it holds for different agents over time.

​
PathSpec

Mirage carries virtual paths through the system using PathSpec, which keeps track of the original path, resolved directory, prefix, and pattern information.

​
Command Execution

Mirage parses commands, resolves virtual paths, dispatches operations to resources, and returns an IOResult. Mirage uses a lightweight async execution model so commands, streams, and cleanup work consistently across local and remote systems without forcing the user into resource-specific APIs. Fingers (ops + FUSE) are the fundamental layer every resource implements; Gestures are the named commands built on fingers; the Shell composes gestures into plans.

​
Recall (Cache)

Remote resources can use cache layers to avoid repeated network reads and to keep directory and file metadata responsive. Mirage calls this system Recall.
  • Deep dive: Recall, the overall Recall model
  • Deep dive: Index Store, remembers directory listings and metadata
  • Deep dive: File Store, remembers file content

​
FUSE

Mirage can also expose the virtual filesystem as a real mount point so non-Mirage tools can read from it directly.

​
Where To Go Next