← Back to Blog

Mirage: A Unified Virtual Filesystem for AI Agents — Complete Guide

2026-05-18

Mirage: A Unified Virtual Filesystem for AI Agents — Complete Guide

AI agents today face a fragmentation problem. Every data source — S3, Gmail, Slack, GitHub, Notion, Redis — speaks its own API with its own SDK, authentication model, and rate limits. An agent that needs to grep Slack logs, copy a file from S3, and summarize a GitHub README must juggle three different SDKs, three authentication flows, and three response formats.

Mirage solves this by presenting every backend as a single virtual filesystem. Agents navigate it with the same bash commands they already know: ls, cat, grep, cp, find. No new SDK to learn. No MCP servers to wire up. Just a unified / tree where S3 lives at /s3, Slack at /slack, Gmail at /gmail, and GitHub at /github.

With 2,361 GitHub stars and rapidly growing, Mirage has become one of the most talked-about infrastructure tools for the AI agent ecosystem since its release in April 2026 by strukto.ai.

Why Mirage Is Trending

Traditional approaches to multi-service agent access have been clunky:

  • MCP (Model Context Protocol) requires running separate servers per service
  • Custom SDK integrations mean rewriting tool bindings for every model
  • LangChain tools add framework lock-in

Mirage takes a radically simpler approach: use the filesystem as the universal API. LLMs are already fluent in bash — the filesystem paradigm is in their training data. By mounting services as directories, Mirage gives agents immediate access to every backend without teaching them a single new concept.

Architecture

Mirage Architecture

Mirage's architecture is a layered virtual filesystem:

  • AI Agent / Application Layer — Claude Code, Codex, OpenAI Agents SDK, Vercel AI SDK, LangChain, or any bash-capable agent
  • Mirage Bash + VFS Layer — A Unix-like shell interpreter that translates commands (ls, cat, cp, grep) into backend-specific operations
  • Dispatcher & Cache Layer — Routes requests to the correct resource mount, with a two-tier cache (RAM or Redis) for performance
  • Infrastructure / Remote Layer — All connected backends: S3, GDrive, Slack, Gmail, GitHub, Redis, Notion, Linear, SSH, and more

Every service speaks the same filesystem semantics, so agents reason about one abstraction instead of N SDKs.

Prerequisites

  • Python ≥ 3.12 (for the Python SDK and CLI)
  • Node.js ≥ 20 (for the TypeScript SDK)
  • macOS or Linux (FUSE-based mounts require platform support)
  • Redis (optional, for shared caching across workers)

Installation

Python (Recommended)

The Python package installs both the library and the CLI:

pip install mirage-ai
# Or with uv:
uv add mirage-ai

TypeScript

Choose the package matching your runtime:

npm install @struktoai/mirage-node      # Node.js servers and CLIs
npm install @struktoai/mirage-browser   # browser / edge runtimes
npm install @struktoai/mirage-core      # runtime-agnostic primitives

CLI (Standalone)

curl -fsSL https://strukto.ai/mirage/install.sh | sh

Or via npm:

npm install -g @struktoai/mirage-cli

Quickstart

Python

Create a workspace that mounts multiple backends side-by-side:

from mirage import Workspace
from mirage.resource.ram import RAMResource
from mirage.resource.s3 import S3Config, S3Resource
from mirage.resource.slack import SlackConfig, SlackResource
from mirage.resource.gdocs import GDocsConfig, GDocsResource

ws = Workspace({
    "/data":  RAMResource(),
    "/s3":    S3Resource(S3Config(bucket="my-bucket")),
    "/slack": SlackResource(SlackConfig()),
    "/docs":  GDocsResource(GDocsConfig()),
})

# Use standard bash commands
await ws.execute("cp /s3/report.csv /data/report.csv")
await ws.execute("grep alert /s3/data/log.jsonl | wc -l")

# Snapshot the entire workspace
ws.snapshot("demo.tar")

TypeScript

The same workspace in TypeScript (works in Node and browser):

import { Workspace, RAMResource, S3Resource, SlackResource, GDocsResource } from '@struktoai/mirage-browser'

const ws = new Workspace({
  '/data':  new RAMResource(),
  '/s3':    new S3Resource({ bucket: 'my-bucket' }),
  '/slack': new SlackResource({}),
  '/docs':  new GDocsResource({}),
})

await ws.execute('cp /s3/report.csv /data/report.csv')
await ws.execute('grep alert /s3/data/log.jsonl | wc -l')

CLI

For direct terminal usage:

# Create a workspace from a YAML config
mirage workspace create ws.yaml --id demo

# Execute commands against it
mirage execute --workspace_id demo --command "cp /s3/report.csv /data/report.csv"

# Snapshot and restore
mirage workspace snapshot demo demo.tar
mirage workspace load demo.tar --id demo-restored

Configuration

YAML Workspace Configuration

Create a ws.yaml to define your mounts declaratively:

id: production
mounts:
  /data:
    type: ram
  /s3:
    type: s3
    config:
      bucket: my-bucket
      region: us-east-1
  /slack:
    type: slack
    config:
      token: ${SLACK_BOT_TOKEN}
  /github:
    type: github
    config:
      token: ${GITHUB_TOKEN}

Then load it:

mirage workspace create ws.yaml --id production
mirage execute --workspace_id production --command "find /github -name '*.md' | head -5"

Redis Cache Configuration

For production deployments with multiple workers, share the cache via Redis:

from mirage import Workspace
from mirage.cache import RedisFileCacheStore, RedisIndexCacheStore

ws = Workspace(
    {"/s3": S3Resource(S3Config(bucket="my-bucket"))},
    cache=RedisFileCacheStore(url="redis://localhost:6379/0", limit="8GB"),
    index=RedisIndexCacheStore(url="redis://localhost:6379/0", ttl=600),
)

Connecting to Agent Frameworks

OpenAI Agents SDK

Plug Mirage as a sandbox into the OpenAI Agents SDK:

from agents import Runner
from agents.run import RunConfig
from agents.sandbox import SandboxAgent, SandboxRunConfig
from mirage.agents.openai_agents import MirageSandboxClient

client = MirageSandboxClient(ws)
agent = SandboxAgent(
    name="Mirage Sandbox Agent",
    model="gpt-5.4-nano",
    instructions=ws.file_prompt,
)

result = await Runner.run(
    agent,
    "Summarize /s3/data/report.parquet into /report.txt.",
    run_config=RunConfig(sandbox=SandboxRunConfig(client=client)),
)

Vercel AI SDK

Expose workspace mounts as AI SDK tools:

import { generateText } from 'ai'
import { openai } from '@ai-sdk/openai'
import { mirageTools } from '@struktoai/mirage-agents/vercel'
import { buildSystemPrompt } from '@struktoai/mirage-agents/openai'

const { text } = await generateText({
  model: openai('gpt-5.4-nano'),
  system: buildSystemPrompt({ mountInfo: { '/': 'In-memory filesystem' } }),
  prompt: "Read /docs/paper.pdf, then describe it.",
  tools: mirageTools(ws),
})

Claude Code / Codex

Use the CLI daemon to give Claude Code direct filesystem access:

mirage workspace create ws.yaml --id claude-workspace
mirage execute --workspace_id claude-workspace --command "cat /github/my-repo/README.md"

Available Resource Mounts

Mirage supports a growing list of backends as resource mounts:

  • Storage — RAM, Disk, S3 / R2 / OCI / Supabase / GCS
  • Communication — Slack, Discord, Telegram, Email (IMAP/SMTP)
  • Productivity — Gmail, Google Drive, Google Docs, Google Sheets, Google Slides
  • Development — GitHub, Linear, Notion, Trello
  • Databases — Redis, MongoDB
  • Infrastructure — SSH (remote filesystem access)

Every mount supports the same bash commands: ls, cat, cp, mv, rm, grep, find, wc, head, tail.

Verification Checklist

  • Mirage CLI installed: mirage --version
  • Workspace created with at least one mount
  • ls on a mount returns expected content
  • cat reads a file from a remote backend
  • grep searches across mount boundaries
  • cp copies between different mounts (e.g., /s3/file → /data/file)
  • Snapshot creates a valid .tar archive
  • Restored workspace has all original data
  • Redis cache configured for multi-worker deployments
  • Agent framework integration works (OpenAI SDK or Vercel AI SDK)

Resources

← Retour au Blog

Mirage : Un Système de Fichiers Virtuel Unifié pour les Agents IA — Guide Complet

2026-05-18

Mirage : Un Système de Fichiers Virtuel Unifié pour les Agents IA — Guide Complet

Les agents IA d'aujourd'hui font face à un problème de fragmentation. Chaque source de données — S3, Gmail, Slack, GitHub, Notion, Redis — parle son propre API avec son propre SDK, son propre modèle d'authentification et ses propres limites de débit. Un agent qui doit fouiller les logs Slack, copier un fichier depuis S3 et résumer un README GitHub doit jongler avec trois SDK différents, trois flux d'authentification et trois formats de réponse.

Mirage résout ce problème en présentant chaque backend comme un système de fichiers virtuel unique. Les agents le parcourent avec les mêmes commandes bash qu'ils connaissent déjà : ls, cat, grep, cp, find. Pas de nouveau SDK à apprendre. Pas de serveurs MCP à câbler. Juste une arborescence / unifiée où S3 vit dans /s3, Slack dans /slack, Gmail dans /gmail et GitHub dans /github.

Avec 2 361 étoiles GitHub et une croissance rapide, Mirage est devenu l'un des outils d'infrastructure les plus discutés de l'écosystème des agents IA depuis sa sortie en avril 2026 par strukto.ai.

Pourquoi Mirage est Tendance

Les approches traditionnelles pour l'accès multi-services des agents sont lourdes :

  • MCP (Model Context Protocol) nécessite l'exécution de serveurs séparés par service
  • Intégrations SDK personnalisées signifient réécrire les liaisons d'outils pour chaque modèle
  • Les outils LangChain ajoutent un verrouillage framework

Mirage adopte une approche radicalement plus simple : utiliser le système de fichiers comme API universelle. Les LLM maîtrisent déjà bash — le paradigme du système de fichiers est dans leurs données d'entraînement. En montant les services comme des répertoires, Mirage donne aux agents un accès immédiat à chaque backend sans leur apprendre un seul nouveau concept.

Architecture

Architecture Mirage

L'architecture de Mirage est un système de fichiers virtuel en couches :

  • Couche Agent IA / Application — Claude Code, Codex, OpenAI Agents SDK, Vercel AI SDK, LangChain, ou tout agent capable de bash
  • Couche Mirage Bash + VFS — Un interpréteur shell de type Unix qui traduit les commandes (ls, cat, cp, grep) en opérations spécifiques au backend
  • Couche Dispatcher & Cache — Achemine les requêtes vers le bon point de montage, avec un cache à deux niveaux (RAM ou Redis) pour les performances
  • Couche Infrastructure / Distante — Tous les backends connectés : S3, GDrive, Slack, Gmail, GitHub, Redis, Notion, Linear, SSH, et plus

Chaque service parle la même sémantique de système de fichiers, donc les agents raisonnent sur une seule abstraction au lieu de N SDK.

Prérequis

  • Python ≥ 3.12 (pour le SDK Python et le CLI)
  • Node.js ≥ 20 (pour le SDK TypeScript)
  • macOS ou Linux (les montages FUSE nécessitent le support de la plateforme)
  • Redis (optionnel, pour le cache partagé entre workers)

Installation

Python (Recommandé)

Le package Python installe à la fois la bibliothèque et le CLI :

pip install mirage-ai
# Ou avec uv :
uv add mirage-ai

TypeScript

Choisissez le package correspondant à votre environnement :

npm install @struktoai/mirage-node      # Serveurs Node.js et CLI
npm install @struktoai/mirage-browser   # Navigateur / edge runtimes
npm install @struktoai/mirage-core      # Primitives agnostiques

CLI (Standalone)

curl -fsSL https://strukto.ai/mirage/install.sh | sh

Ou via npm :

npm install -g @struktoai/mirage-cli

Démarrage Rapide

Python

Créez un espace de travail qui monte plusieurs backends côte à côte :

from mirage import Workspace
from mirage.resource.ram import RAMResource
from mirage.resource.s3 import S3Config, S3Resource
from mirage.resource.slack import SlackConfig, SlackResource

ws = Workspace({
    "/data":  RAMResource(),
    "/s3":    S3Resource(S3Config(bucket="mon-bucket")),
    "/slack": SlackResource(SlackConfig()),
})

# Utilisez des commandes bash standard
await ws.execute("cp /s3/report.csv /data/report.csv")
await ws.execute("grep alert /s3/data/log.jsonl | wc -l")

# Instantané de tout l'espace de travail
ws.snapshot("demo.tar")

TypeScript

Le même espace de travail en TypeScript :

import { Workspace, RAMResource, S3Resource, SlackResource } from '@struktoai/mirage-browser'

const ws = new Workspace({
  '/data':  new RAMResource(),
  '/s3':    new S3Resource({ bucket: 'mon-bucket' }),
  '/slack': new SlackResource({}),
})

await ws.execute('cp /s3/report.csv /data/report.csv')
await ws.execute('grep alert /s3/data/log.jsonl | wc -l')

CLI

Pour une utilisation directe en terminal :

# Créer un espace de travail depuis un fichier YAML
mirage workspace create ws.yaml --id demo

# Exécuter des commandes
mirage execute --workspace_id demo --command "cp /s3/report.csv /data/report.csv"

# Instantané et restauration
mirage workspace snapshot demo demo.tar
mirage workspace load demo.tar --id demo-restored

Configuration

Configuration YAML de l'Espace de Travail

Créez un ws.yaml pour définir vos montages de manière déclarative :

id: production
mounts:
  /data:
    type: ram
  /s3:
    type: s3
    config:
      bucket: mon-bucket
      region: us-east-1
  /slack:
    type: slack
    config:
      token: ${SLACK_BOT_TOKEN}
  /github:
    type: github
    config:
      token: ${GITHUB_TOKEN}

Puis chargez-le :

mirage workspace create ws.yaml --id production
mirage execute --workspace_id production --command "find /github -name '*.md' | head -5"

Configuration du Cache Redis

Pour les déploiements de production avec plusieurs workers, partagez le cache via Redis :

from mirage import Workspace
from mirage.cache import RedisFileCacheStore, RedisIndexCacheStore

ws = Workspace(
    {"/s3": S3Resource(S3Config(bucket="mon-bucket"))},
    cache=RedisFileCacheStore(url="redis://localhost:6379/0", limit="8GB"),
    index=RedisIndexCacheStore(url="redis://localhost:6379/0", ttl=600),
)

Connexion aux Frameworks d'Agents

OpenAI Agents SDK

Branchez Mirage comme sandbox dans l'OpenAI Agents SDK :

from agents import Runner, RunConfig
from agents.sandbox import SandboxAgent, SandboxRunConfig
from mirage.agents.openai_agents import MirageSandboxClient

client = MirageSandboxClient(ws)
agent = SandboxAgent(
    name="Agent Sandbox Mirage",
    model="gpt-5.4-nano",
    instructions=ws.file_prompt,
)

result = await Runner.run(
    agent,
    "Résume /s3/data/report.parquet dans /report.txt.",
    run_config=RunConfig(sandbox=SandboxRunConfig(client=client)),
)

Vercel AI SDK

Exposez les montages de l'espace de travail comme outils AI SDK :

import { generateText } from 'ai'
import { openai } from '@ai-sdk/openai'
import { mirageTools } from '@struktoai/mirage-agents/vercel'
import { buildSystemPrompt } from '@struktoai/mirage-agents/openai'

const { text } = await generateText({
  model: openai('gpt-5.4-nano'),
  system: buildSystemPrompt({ mountInfo: { '/': 'Système de fichiers en mémoire' } }),
  prompt: "Lis /docs/paper.pdf, puis décris-le.",
  tools: mirageTools(ws),
})

Points de Montage Disponibles

Mirage supporte une liste croissante de backends comme points de montage :

  • Stockage — RAM, Disque, S3 / R2 / OCI / Supabase / GCS
  • Communication — Slack, Discord, Telegram, Email (IMAP/SMTP)
  • Productivité — Gmail, Google Drive, Google Docs, Google Sheets, Google Slides
  • Développement — GitHub, Linear, Notion, Trello
  • Bases de données — Redis, MongoDB
  • Infrastructure — SSH (accès distant au système de fichiers)

Chaque montage supporte les mêmes commandes bash : ls, cat, cp, mv, rm, grep, find, wc, head, tail.

Liste de Vérification

  • CLI Mirage installé : mirage --version
  • Espace de travail créé avec au moins un montage
  • ls sur un montage retourne le contenu attendu
  • cat lit un fichier depuis un backend distant
  • grep cherche à travers les limites des montages
  • cp copie entre différents montages
  • L'instantané crée une archive .tar valide
  • L'espace de travail restauré a toutes les données originales
  • Cache Redis configuré pour les déploiements multi-workers
  • L'intégration avec le framework d'agents fonctionne

Ressources