Mirage : guide pratique du systeme de fichiers virtuel pour agents IA

Mirage est un systeme de fichiers virtuel unifie pour agents IA. Au lieu de donner a l’agent une API differente pour chaque service, Mirage monte les ressources dans un seul arbre : /s3, /github, /slack, /gmail, /linear, /redis, /postgres, /data, etc.

L’idee est puissante parce que les LLM comprennent deja les workflows shell. Ils savent utiliser ls, cat, grep, find, les pipes, les globs, les redirections et les chemins de fichiers. Mirage transforme cette competence en interface multi-service.

Ce guide est mon propre parcours d’apprentissage :

• Quand utiliser Mirage plutot qu’un outil MCP dedie ?
• Comment construire un workspace ?
• Que fait vraiment le shell Mirage ?
• Comment fonctionnent cache, provision, snapshot et replay ?
• Quelles sont les limites Python, Node, navigateur et FUSE ?

Sources : GitHub Mirage, index docs, introduction, installation, CLI, architecture, shell, resource matrix, snapshot/replay, Python install et limitations TypeScript.

Le probleme que Mirage resout

Les systemes d’agents grandissent souvent par empilement d’outils : GitHub, S3, Slack, Linear, Gmail, Postgres, Redis. Chaque service ajoute son schema, sa pagination, ses erreurs, son modele d’autorisation et sa syntaxe.

L’agent doit apprendre une nouvelle interface a chaque fois.

Mirage propose une autre abstraction : tout devient un chemin.

/
├── data/
├── s3/
├── github/
├── slack/
├── linear/
├── postgres/
└── redis/

Puis l’agent peut faire :

ls /github/my-org/my-repo
grep -r "timeout" /slack/engineering /github/my-org/my-repo
cat /s3/logs/app.jsonl | wc -l
cp /github/my-org/my-repo/README.md /data/readme.md

Le filesystem devient l’API.

Selectionnez un mount.

Installation

Python :

uv add mirage-ai
# ou
pip install mirage-ai

Extras :

pip install "mirage-ai[s3]"
pip install "mirage-ai[redis]"
pip install "mirage-ai[fuse]"

TypeScript :

pnpm add @struktoai/mirage-node
pnpm add @struktoai/mirage-browser
pnpm add @struktoai/mirage-agents

CLI :

curl -fsSL https://strukto.ai/mirage/install.sh | sh
npm install -g @struktoai/mirage-cli
uvx mirage-ai

Prerequis :

• Python 3.12+ ;
• Node.js 20+ ;
• macOS ou Linux pour FUSE.

Je conseille d’apprendre Mirage sans FUSE d’abord. Utilisez Workspace et execute(). Ajoutez FUSE seulement si des outils host doivent voir Mirage comme un vrai filesystem monte.

Premier workspace RAM

from mirage import Workspace
from mirage.resources import RAMResource

ws = Workspace({
    "/data": RAMResource(),
})

ws.execute("echo hello > /data/hello.txt")
result = ws.execute("cat /data/hello.txt")
print(result.stdout)

Concepts :

• Workspace possede les mounts.
• Un chemin comme /data pointe vers une ressource.
• execute() lance un shell Mirage.
• Le shell est bash-like, mais ce n’est pas un /bin/bash brut.

Mirage parse les commandes avec tree-sitter puis les execute via son runtime VFS. Certaines commandes shell ne sont pas supportees, comme bg, disown, exec, complete, compgen, ulimit ou la substitution de processus >(cmd).

Ajouter des mounts reels

from mirage import Workspace
from mirage.resources import RAMResource, S3Resource, GitHubResource

ws = Workspace({
    "/data": RAMResource(),
    "/s3": S3Resource(bucket="my-bucket"),
    "/github": GitHubResource(token="...", owner="my-org"),
})

ws.execute('grep -r "retry" /github/my-repo/src > /data/retry-notes.txt')
ws.execute('cp /data/retry-notes.txt /s3/reports/retry-notes.txt')

Les arguments exacts dependent de la ressource, mais le modele reste identique : config au moment du mount, chemins ensuite.

Modes utiles :

• read pour inspecter ;
• write pour creer/modifier ;
• exec pour operations executables.

Pour les agents, je partirais en lecture seule par defaut et j’ouvrirais l’ecriture seulement sur des mounts explicites.

CLI et YAML

mounts:
  /data:
    type: ram
  /repo:
    type: disk
    path: .
  /s3:
    type: s3
    bucket: my-bucket

Commandes :

mirage workspace create demo -f workspace.yaml
mirage exec demo 'find /repo -name "*.md" | head'
mirage exec demo 'grep -r "Mirage" /repo /s3'

La CLI utilise un daemon local HTTP, lance automatiquement au besoin, puis arrete apres inactivite.

Provision et cache

provision estime une commande avant de l’executer : octets reseau, hits cache, cout potentiel.

mirage provision demo 'grep -r "timeout" /s3/logs /slack/engineering'

Cache :

1. ls /s3/logs remplit l’index cache.
2. find /s3/logs -name "*.jsonl" reutilise les listings.
3. cat /s3/logs/app.jsonl remplit le file cache.
4. grep ERROR /s3/logs/app.jsonl reutilise les bytes.

Cliquez pour simuler.

Snapshot et replay

Les runs d’agents sont difficiles a reproduire : Slack change, GitHub bouge, S3 peut etre ecrase, une API depend du temps.

Mirage peut capturer :

• config des mounts ;
• sessions ;
• historique commandes ;
• jobs termines ;
• bytes en cache ;
• fingerprints des chemins lus.

mirage workspace snapshot demo /tmp/demo.tar
mirage workspace load /tmp/demo.tar --id demo_loaded --override workspace.yaml

Les credentials sont redactes et doivent etre fournis a nouveau.

Limite importante : ce n’est pas une machine a remonter le temps universelle. Les ressources live comme Gmail, Slack, Linear ou Notion ne garantissent pas toujours un etat complet. Mirage fingerprint surtout ce qui a ete touche/lu.

Architecture

Mirage suit quatre couches :

1. Agent ou application.
2. Mirage Bash + VFS.
3. Dispatcher + cache.
4. Ressources distantes : RAM, disque, S3, GitHub, Slack, Google Workspace, bases de donnees, Redis, SSH.

Agent IA / app
      |
Mirage shell + VFS
      |
Dispatcher + cache
      |
      +-- /data    -> RAM / disque
      +-- /s3      -> object storage
      +-- /github  -> GitHub API
      +-- /slack   -> Slack API
      +-- /redis   -> Redis
      +-- /postgres-> Postgres

FUSE est optionnel. Sans FUSE, Mirage fonctionne in-process. Avec FUSE, l’OS voit l’arbre Mirage comme un filesystem monte.

Python, Node, navigateur

Python est le chemin le plus direct pour beaucoup de workflows agents.

Node est utile pour TypeScript, mais attention :

• FUSE + native exec dans le meme process peut deadlock ;
• fs-monkey patch require("fs"), pas node:fs ESM ;
• certaines lectures FUSE de ressources API a taille inconnue sont limitees.

Navigateur :

• pas de FUSE ;
• pas d’execution de sous-processus native ;
• ressources HTTP soumises a CORS/PKCE/presigned URLs/proxy ;
• OPFS a quotas et eviction possible ;
• SSH, Postgres, MongoDB, Email et FUSE sont Node-only.

Choisissez donc le runtime avant de choisir les ressources.

Patterns agents

Incident :

grep -r "payment timeout" /slack/engineering > /data/slack-context.txt
grep -r "timeout" /github/company/api/src > /data/code-context.txt
cat /data/slack-context.txt /data/code-context.txt > /data/incident-brief.md

Audit documentation :

find /github/company/docs -name "*.md" > /data/repo-docs.txt
find /gdrive/ProductDocs -name "*.gdoc.json" > /data/drive-docs.txt
grep -r "deprecated" /github/company/docs /gdrive/ProductDocs

Pipeline data :

cat /s3/events/2026-05-15.jsonl | grep checkout > /data/checkout-events.jsonl
wc -l /data/checkout-events.jsonl

Mirage vs MCP vs API directe

Utilisez Mirage quand :

• plusieurs ressources doivent etre explorees avec le meme modele mental ;
• grep, find, cat, cp et les pipes sont naturels ;
• cache, provision et replay sont utiles ;
• l’agent doit produire des fichiers intermediaires.

Utilisez une API directe ou un outil MCP dedie quand :

• l’action est transactionnelle ;
• le domaine ne se mappe pas bien a des fichiers ;
• vous voulez une action tres etroite et auditable.

Utilisez un sandbox reel quand :

• du code non fiable s’execute ;
• l’isolation OS/reseau est necessaire ;
• Mirage VFS ne suffit pas.

Mirage n’est pas un sandbox OS complet.

Mon parcours d’apprentissage

1. Workspace RAM.
2. echo, cat, ls.
3. Mount disque local.
4. Mount S3 ou GitHub.
5. grep, find, pipes et redirections entre deux mounts.
6. provision avant une lecture large.
7. Snapshot puis restore.
8. Slack, Linear, Gmail ou autre SaaS.
9. FUSE en dernier.

La competence cle est de penser en chemins :

Que peut lire l'agent ?
Ou ecrit-il son travail intermediaire ?
Quelles donnees distantes doivent etre cachees ?
Quelle commande doit etre estimee avant execution ?
Quel run doit etre snapshotte ?

Si ces questions sont claires, Mirage devient une abstraction serieuse pour agents IA : un seul filesystem au-dessus de nombreux services.