{"id":50055602,"url":"https://github.com/strukto-ai/mirage","last_synced_at":"2026-05-21T15:01:22.678Z","repository":{"id":356495115,"uuid":"1231135337","full_name":"strukto-ai/mirage","owner":"strukto-ai","description":"A Unified Virtual Filesystem For AI Agents","archived":false,"fork":false,"pushed_at":"2026-05-15T20:10:59.000Z","size":10702,"stargazers_count":2280,"open_issues_count":18,"forks_count":150,"subscribers_count":9,"default_branch":"main","last_synced_at":"2026-05-15T20:44:37.301Z","etag":null,"topics":["agent-sandbox","agent-tools","ai-agents","bash","claude-code","fuse","langchain","llm-agents","openai-agents","python","typescript","vfs","virtual-filesystem"],"latest_commit_sha":null,"homepage":"https://www.strukto.ai/mirage","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/strukto-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-06T17:00:48.000Z","updated_at":"2026-05-15T20:34:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/strukto-ai/mirage","commit_stats":null,"previous_names":["strukto-ai/mirage"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/strukto-ai/mirage","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strukto-ai%2Fmirage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strukto-ai%2Fmirage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strukto-ai%2Fmirage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strukto-ai%2Fmirage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/strukto-ai","download_url":"https://codeload.github.com/strukto-ai/mirage/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strukto-ai%2Fmirage/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33305277,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-21T12:23:38.849Z","status":"ssl_error","status_checked_at":"2026-05-21T12:22:11.673Z","response_time":62,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-sandbox","agent-tools","ai-agents","bash","claude-code","fuse","langchain","llm-agents","openai-agents","python","typescript","vfs","virtual-filesystem"],"created_at":"2026-05-21T13:00:32.106Z","updated_at":"2026-05-21T15:01:22.638Z","avatar_url":"https://github.com/strukto-ai.png","language":"TypeScript","funding_links":[],"categories":["Design Primitives","AI开源项目","Agent Ecosystem","TypeScript","Agent Infrastructure"],"sub_categories":["Context Delivery \u0026 Compaction","AI 工具","Harness Engineering","Sandboxing \u0026 Execution"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/mirage-og-light@2x.png\" alt=\"Mirage: A Unified Virtual File System for AI Agents\" width=\"900\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://docs.mirage.strukto.ai\" alt=\"Documentation\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/mirage-docs-0C0C0C?labelColor=FAFAFA\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://www.strukto.ai\" alt=\"Website\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/made by-strukto.ai-0C0C0C?labelColor=FAFAFA\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/strukto-ai/mirage/blob/main/LICENSE\" alt=\"License\"\u003e\n        \u003cimg src=\"https://img.shields.io/github/license/strukto-ai/mirage?color=0C0C0C\u0026labelColor=FAFAFA\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://discord.gg/u8BPQ65KsS\" alt=\"Discord\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/discord-join-0C0C0C?labelColor=FAFAFA\u0026logo=discord\u0026logoColor=0C0C0C\" /\u003e\u003c/a\u003e\n    \u003cbr/\u003e\n    \u003ca href=\"https://docs.mirage.strukto.ai/python/quickstart\" alt=\"Python docs\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/python-docs-0C0C0C?labelColor=FAFAFA\u0026logo=python\u0026logoColor=0C0C0C\" alt=\"Python docs\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://pypi.org/project/mirage-ai/\" alt=\"PyPI Version\"\u003e\n        \u003cimg src=\"https://img.shields.io/pypi/v/mirage-ai.svg?color=0C0C0C\u0026labelColor=FAFAFA\"/\u003e\u003c/a\u003e\n    \u003cbr/\u003e\n    \u003ca href=\"https://docs.mirage.strukto.ai/typescript/quickstart\" alt=\"TypeScript docs\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/typescript-docs-0C0C0C?labelColor=FAFAFA\u0026logo=typescript\u0026logoColor=0C0C0C\" alt=\"TypeScript docs\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://www.npmjs.com/package/@struktoai/mirage-node\" alt=\"NPM Version\"\u003e\n        \u003cimg src=\"https://img.shields.io/npm/v/@struktoai/mirage-node.svg?color=0C0C0C\u0026labelColor=FAFAFA\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nMirage is **a Unified Virtual File System for AI Agents**: a single tree that mounts services and data sources like S3, Google Drive, Slack, Gmail, and Redis side-by-side as one filesystem.\n\nAI agents reach every backend with the same handful of Unix-like tools, and pipelines compose across services as naturally as on a local disk. It's a simulated environment, agents see one filesystem underneath. Any LLM that already knows bash can use Mirage out of the box, with zero new vocabulary.\n\n```ts\nconst ws = new Workspace({\n  '/data':   new RAMResource(),\n  '/s3':     new S3Resource({ bucket: 'logs' }),\n  '/slack':  new SlackResource({}),\n  '/github': new GitHubResource({}),\n})\n\nawait ws.execute('grep alert /slack/general/*.json | wc -l')\nawait ws.execute('cat /github/mirage/README.md')\nawait ws.execute('cp /s3/report.csv /data/local.csv')\n\n// Register a new command, available across every mount.\nws.command('summarize', ...)\n\n// Override a command for a specific resource + filetype —\n// `cat` on a Parquet file in /s3 renders rows as JSON instead of raw bytes.\nws.command('cat', { resource: 's3', filetype: 'parquet' }, ...)\n\nawait ws.execute('summarize /github/mirage/README.md')\nawait ws.execute('cat /s3/events/2026-05-06.parquet | jq .user')\n```\n\n## About\n\n- **One filesystem, every backend.** Every service speaks the same filesystem semantics, so agents reason about one abstraction instead of N SDKs and M MCPs, leaning on the filesystem and bash vocabulary LLMs are most fluent in.\n- **Multiple resources, one filesystem:** RAM, Disk, Redis, S3 / R2 / OCI / Supabase / GCS, Gmail / GDrive / GDocs / GSheets / GSlides, GitHub / Linear / Notion / Trello, Slack / Discord / Telegram / Email, MongoDB, SSH, and more, mounted side-by-side under a single root.\n- **Familiar bash tools across every mount.** Agents reuse the same handful of Unix-like tools instead of learning a new API per service, and pipelines compose across services as naturally as on a local disk, the exact corpus modern LLMs are most heavily trained on.\n- **Portable workspaces:** clone, snapshot, and version your environment. Move agent runs between machines without restarting or reconfiguring the system.\n- **Embed in your apps and services:** Python and TypeScript SDKs let you give your AI agents a virtual filesystem directly inside FastAPI, Express, browser apps, or any async runtime, no separate process required. Clone, snapshot, and version the workspace from inside your code.\n- **Works with major agent application frameworks:** OpenAI Agents SDK, Vercel AI SDK (TypeScript), LangChain, Pydantic AI, CAMEL, and OpenHands.\n- **Lightweight CLI + daemon:** plugs into coding agents like Claude Code and Codex so they reach every mounted resource through familiar bash, getting more useful work done per turn.\n\n## Architecture\n\n\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets/mirage-arch-dark.svg\"\u003e\n    \u003cimg src=\"assets/mirage-arch-light.svg\" alt=\"Mirage architecture: AI Agent and Application → Mirage Bash and VFS → Dispatcher \u0026amp; Cache → Infrastructure and Remote\" width=\"900\"\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\n## Installation\n\n### Prerequisites\n\n- **Python** ≥ 3.12 for the `mirage-ai` package and the `mirage` CLI\n- **Node.js** ≥ 20 for the TypeScript SDK\n- **macOS** or **Linux** (FUSE-based mounts require platform support)\n\n### Python\n\n```bash\nuv add mirage-ai\n```\n\nThis installs both the `mirage` library and the `mirage` CLI binary.\n\n### TypeScript\n\nPick the package that matches your runtime:\n\n```bash\nnpm install @struktoai/mirage-node      # Node.js servers and CLIs\nnpm install @struktoai/mirage-browser   # browser / edge runtimes\nnpm install @struktoai/mirage-core      # runtime-agnostic primitives\n```\n\n`@struktoai/mirage-node` and `@struktoai/mirage-browser` both pull in `@struktoai/mirage-core` automatically.\n\n### CLI\n\n```bash\ncurl -fsSL https://strukto.ai/mirage/install.sh | sh\n```\n\nOr via your package manager of choice:\n\n```bash\nnpm install -g @struktoai/mirage-cli\n```\n\n```bash\nuvx mirage-ai\n```\n\n```bash\nnpx @struktoai/mirage-cli\n```\n\n## Quickstart (Python)\n\n```python\nfrom mirage import Workspace\nfrom mirage.resource.gdocs import GDocsConfig, GDocsResource\nfrom mirage.resource.ram import RAMResource\nfrom mirage.resource.s3 import S3Config, S3Resource\nfrom mirage.resource.slack import SlackConfig, SlackResource\n\nws = Workspace({\n    \"/data\":  RAMResource(),\n    \"/s3\":    S3Resource(S3Config(bucket=\"my-bucket\")),\n    \"/slack\": SlackResource(SlackConfig()),\n    \"/docs\":  GDocsResource(GDocsConfig()),\n})\n\nawait ws.execute(\"cp /s3/report.csv /data/report.csv\")\nawait ws.execute(\"grep alert /s3/data/log.jsonl | wc -l\")\n\nws.snapshot(\"demo.tar\")\n```\n\n## Quickstart (TypeScript)\n\n```ts\nimport {\n  Workspace,\n  RAMResource,\n  S3Resource,\n  SlackResource,\n  GDocsResource,\n} from '@struktoai/mirage-browser'\n\nconst ws = new Workspace({\n  '/data':  new RAMResource(),\n  '/s3':    new S3Resource({ bucket: 'my-bucket' }),\n  '/slack': new SlackResource({}),\n  '/docs':  new GDocsResource({}),\n})\n\nawait ws.execute('cp /s3/report.csv /data/report.csv')\nawait ws.execute('grep alert /s3/data/log.jsonl | wc -l')\n```\n\n## Quickstart (CLI)\n\n```bash\nmirage workspace create ws.yaml --id demo\nmirage execute   --workspace_id demo --command \"cp /s3/report.csv /data/report.csv\"\nmirage provision --workspace_id demo --command \"cat /s3/data/large.jsonl\"\nmirage workspace snapshot demo demo.tar\nmirage workspace load demo.tar --id demo-restored\n```\n\n## Agent Frameworks\n\nMirage drops into the major agent application frameworks as a sandbox or tool layer. Your agent runs against the same mount tree it would in bash, so swapping the model or runtime never changes the surface.\n\n### OpenAI Agents SDK (Python)\n\nThe `MirageSandboxClient` plugs a `Workspace` into the OpenAI Agents SDK as a sandbox: bash commands the agent runs execute against your mounts.\n\n```python\nfrom agents import Runner\nfrom agents.run import RunConfig\nfrom agents.sandbox import SandboxAgent, SandboxRunConfig\n\nfrom mirage.agents.openai_agents import MirageSandboxClient\n\nclient = MirageSandboxClient(ws)\nagent = SandboxAgent(\n    name=\"Mirage Sandbox Agent\",\n    model=\"gpt-5.4-nano\",\n    instructions=ws.file_prompt,\n)\n\nresult = await Runner.run(\n    agent,\n    \"Summarize /s3/data/report.parquet into /report.txt.\",\n    run_config=RunConfig(sandbox=SandboxRunConfig(client=client)),\n)\n```\n\n### Vercel AI SDK (TypeScript)\n\n`mirageTools(ws)` exposes the workspace as a typed AI SDK tool set, so any model wired into the AI SDK can read and write across mounts, in Node or the browser.\n\n```ts\nimport { generateText } from 'ai'\nimport { openai } from '@ai-sdk/openai'\nimport { mirageTools } from '@struktoai/mirage-agents/vercel'\nimport { buildSystemPrompt } from '@struktoai/mirage-agents/openai'\n\nconst { text } = await generateText({\n  model: openai('gpt-5.4-nano'),\n  system: buildSystemPrompt({ mountInfo: { '/': 'In-memory filesystem' } }),\n  prompt: \"Use readFile to read /docs/paper.pdf, then describe what's in it.\",\n  tools: mirageTools(ws),\n})\n```\n\nLangChain, Pydantic AI, CAMEL, OpenHands, and Mastra adapters live alongside these.\n\n## Cache\n\nEvery `Workspace` ships with a **two-layer cache** so repeated work against remote backends (S3, GDrive, Slack, …) hits local state instead of the network:\n\n- **Index cache.** Listings and metadata. The first directory walk hits the API; subsequent ones serve from the index until TTL expires.\n- **File cache.** Object bytes. The first read streams from origin; later pipelines read from cache.\n- **Pluggable backends.** Each layer is a store with two built-ins:\n  - **RAM** (default): in-process, zero setup, 512 MB file cache and 10-minute index TTL. Best for single-process apps and notebooks.\n  - **Redis**: shared across workers, processes, and machines. Best for serverless, multi-replica services, or when you want cache state to survive restarts.\n\n```ts\nimport { RedisFileCacheStore, RedisIndexCacheStore, Workspace } from 'mirage/node'\n\nconst ws = new Workspace(\n  { '/s3': new S3Resource({ bucket: 'my-bucket' }) },\n  {\n    cache: new RedisFileCacheStore({ url: 'redis://localhost:6379/0', limit: '8GB' }),\n    index: new RedisIndexCacheStore({ url: 'redis://localhost:6379/0', ttl: 600 }),\n  },\n)\n```\n\n```ts\nimport { S3Resource, Workspace } from 'mirage/node'\n\nconst ws = new Workspace({ '/s3': new S3Resource({ bucket: 'my-bucket' }) })\n\n// 1. Index miss → S3 LIST. Listing stored in index cache.\nawait ws.execute('ls /s3/data/')\n\n// 2. Index hit → 0 network calls.\nawait ws.execute('find /s3/data/ -name \"*.jsonl\"')\n\n// 3. File miss → S3 GET. Bytes stored in file cache.\nawait ws.execute('cat /s3/data/log.jsonl | wc -l')\n\n// 4. File hit → 0 network calls.\nawait ws.execute('grep alert /s3/data/log.jsonl')\n```\n\n## Contributors\n\nThanks to everyone who has contributed to Mirage.\n\n\u003ca href=\"https://github.com/strukto-ai/mirage/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contrib.rocks/image?repo=strukto-ai/mirage\" alt=\"Mirage contributors\" /\u003e\n\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstrukto-ai%2Fmirage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstrukto-ai%2Fmirage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstrukto-ai%2Fmirage/lists"}