[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-11116":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":23,"hasPages":23,"topics":25,"createdAt":10,"pushedAt":10,"updatedAt":39,"readmeContent":40,"aiSummary":41,"trendingCount":16,"starSnapshotCount":16,"syncStatus":42,"lastSyncTime":43,"discoverSource":44},11116,"mirage","strukto-ai\u002Fmirage","strukto-ai","A Unified Virtual Filesystem For AI Agents","https:\u002F\u002Fwww.strukto.ai\u002Fmirage",null,"TypeScript",3124,220,11,77,0,47,88,1119,141,109.03,"Apache License 2.0",false,"main",[26,27,28,29,30,31,32,33,34,35,36,37,38],"agent-sandbox","agent-tools","ai-agents","bash","claude-code","fuse","langchain","llm-agents","openai-agents","python","typescript","vfs","virtual-filesystem","2026-06-12 04:00:53","\u003Cp align=\"center\">\n  \u003Cimg src=\"assets\u002Fmirage-og-light@2x.png\" alt=\"Mirage: A Unified Virtual File System for AI Agents\" width=\"900\">\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n    \u003Ca href=\"https:\u002F\u002Fdocs.mirage.strukto.ai\" alt=\"Documentation\">\n        \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fmirage-docs-0C0C0C?labelColor=FAFAFA\" \u002F>\u003C\u002Fa>\n    \u003Ca href=\"https:\u002F\u002Fwww.strukto.ai\" alt=\"Website\">\n        \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fmade by-strukto.ai-0C0C0C?labelColor=FAFAFA\" \u002F>\u003C\u002Fa>\n    \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fstrukto-ai\u002Fmirage\u002Fblob\u002Fmain\u002FLICENSE\" alt=\"License\">\n        \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Flicense\u002Fstrukto-ai\u002Fmirage?color=0C0C0C&labelColor=FAFAFA\" \u002F>\u003C\u002Fa>\n    \u003Ca href=\"https:\u002F\u002Fdiscord.gg\u002Fu8BPQ65KsS\" alt=\"Discord\">\n        \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fdiscord-join-0C0C0C?labelColor=FAFAFA&logo=discord&logoColor=0C0C0C\" \u002F>\u003C\u002Fa>\n    \u003Cbr\u002F>\n    \u003Ca href=\"https:\u002F\u002Fdocs.mirage.strukto.ai\u002Fpython\u002Fquickstart\" alt=\"Python docs\">\n        \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fpython-docs-0C0C0C?labelColor=FAFAFA&logo=python&logoColor=0C0C0C\" alt=\"Python docs\">\u003C\u002Fa>\n    \u003Ca href=\"https:\u002F\u002Fpypi.org\u002Fproject\u002Fmirage-ai\u002F\" alt=\"PyPI Version\">\n        \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Fmirage-ai.svg?color=0C0C0C&labelColor=FAFAFA\"\u002F>\u003C\u002Fa>\n    \u003Cbr\u002F>\n    \u003Ca href=\"https:\u002F\u002Fdocs.mirage.strukto.ai\u002Ftypescript\u002Fquickstart\" alt=\"TypeScript docs\">\n        \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Ftypescript-docs-0C0C0C?labelColor=FAFAFA&logo=typescript&logoColor=0C0C0C\" alt=\"TypeScript docs\">\u003C\u002Fa>\n    \u003Ca href=\"https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002F@struktoai\u002Fmirage-node\" alt=\"NPM Version\">\n        \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002F@struktoai\u002Fmirage-node.svg?color=0C0C0C&labelColor=FAFAFA\"\u002F>\u003C\u002Fa>\n\u003C\u002Fp>\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  '\u002Fdata':   new RAMResource(),\n  '\u002Fs3':     new S3Resource({ bucket: 'logs' }),\n  '\u002Fslack':  new SlackResource({}),\n  '\u002Fgithub': new GitHubResource({}),\n})\n\nawait ws.execute('grep alert \u002Fslack\u002Fgeneral\u002F*.json | wc -l')\nawait ws.execute('cat \u002Fgithub\u002Fmirage\u002FREADME.md')\nawait ws.execute('cp \u002Fs3\u002Freport.csv \u002Fdata\u002Flocal.csv')\n\n\u002F\u002F Register a new command, available across every mount.\nws.command('summarize', ...)\n\n\u002F\u002F Override a command for a specific resource + filetype —\n\u002F\u002F `cat` on a Parquet file in \u002Fs3 renders rows as JSON instead of raw bytes.\nws.command('cat', { resource: 's3', filetype: 'parquet' }, ...)\n\nawait ws.execute('summarize \u002Fgithub\u002Fmirage\u002FREADME.md')\nawait ws.execute('cat \u002Fs3\u002Fevents\u002F2026-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 \u002F R2 \u002F OCI \u002F Supabase \u002F GCS, Gmail \u002F GDrive \u002F GDocs \u002F GSheets \u002F GSlides, GitHub \u002F Linear \u002F Notion \u002F Trello, Slack \u002F Discord \u002F Telegram \u002F 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\">\n  \u003Cpicture>\n    \u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets\u002Fmirage-arch-dark.svg\">\n    \u003Cimg src=\"assets\u002Fmirage-arch-light.svg\" alt=\"Mirage architecture: AI Agent and Application → Mirage Bash and VFS → Dispatcher & Cache → Infrastructure and Remote\" width=\"900\">\n  \u003C\u002Fpicture>\n\u003C\u002Fp>\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\u002Fmirage-node      # Node.js servers and CLIs\nnpm install @struktoai\u002Fmirage-browser   # browser \u002F edge runtimes\nnpm install @struktoai\u002Fmirage-core      # runtime-agnostic primitives\n```\n\n`@struktoai\u002Fmirage-node` and `@struktoai\u002Fmirage-browser` both pull in `@struktoai\u002Fmirage-core` automatically.\n\n### CLI\n\n```bash\ncurl -fsSL https:\u002F\u002Fstrukto.ai\u002Fmirage\u002Finstall.sh | sh\n```\n\nOr via your package manager of choice:\n\n```bash\nnpm install -g @struktoai\u002Fmirage-cli\n```\n\n```bash\nuvx mirage-ai\n```\n\n```bash\nnpx @struktoai\u002Fmirage-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    \"\u002Fdata\":  RAMResource(),\n    \"\u002Fs3\":    S3Resource(S3Config(bucket=\"my-bucket\")),\n    \"\u002Fslack\": SlackResource(SlackConfig()),\n    \"\u002Fdocs\":  GDocsResource(GDocsConfig()),\n})\n\nawait ws.execute(\"cp \u002Fs3\u002Freport.csv \u002Fdata\u002Freport.csv\")\nawait ws.execute(\"grep alert \u002Fs3\u002Fdata\u002Flog.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\u002Fmirage-browser'\n\nconst ws = new Workspace({\n  '\u002Fdata':  new RAMResource(),\n  '\u002Fs3':    new S3Resource({ bucket: 'my-bucket' }),\n  '\u002Fslack': new SlackResource({}),\n  '\u002Fdocs':  new GDocsResource({}),\n})\n\nawait ws.execute('cp \u002Fs3\u002Freport.csv \u002Fdata\u002Freport.csv')\nawait ws.execute('grep alert \u002Fs3\u002Fdata\u002Flog.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 \u002Fs3\u002Freport.csv \u002Fdata\u002Freport.csv\"\nmirage provision --workspace_id demo --command \"cat \u002Fs3\u002Fdata\u002Flarge.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 \u002Fs3\u002Fdata\u002Freport.parquet into \u002Freport.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\u002Fopenai'\nimport { mirageTools } from '@struktoai\u002Fmirage-agents\u002Fvercel'\nimport { buildSystemPrompt } from '@struktoai\u002Fmirage-agents\u002Fopenai'\n\nconst { text } = await generateText({\n  model: openai('gpt-5.4-nano'),\n  system: buildSystemPrompt({ mountInfo: { '\u002F': 'In-memory filesystem' } }),\n  prompt: \"Use readFile to read \u002Fdocs\u002Fpaper.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\u002Fnode'\n\nconst ws = new Workspace(\n  { '\u002Fs3': new S3Resource({ bucket: 'my-bucket' }) },\n  {\n    cache: new RedisFileCacheStore({ url: 'redis:\u002F\u002Flocalhost:6379\u002F0', limit: '8GB' }),\n    index: new RedisIndexCacheStore({ url: 'redis:\u002F\u002Flocalhost:6379\u002F0', ttl: 600 }),\n  },\n)\n```\n\n```ts\nimport { S3Resource, Workspace } from 'mirage\u002Fnode'\n\nconst ws = new Workspace({ '\u002Fs3': new S3Resource({ bucket: 'my-bucket' }) })\n\n\u002F\u002F 1. Index miss → S3 LIST. Listing stored in index cache.\nawait ws.execute('ls \u002Fs3\u002Fdata\u002F')\n\n\u002F\u002F 2. Index hit → 0 network calls.\nawait ws.execute('find \u002Fs3\u002Fdata\u002F -name \"*.jsonl\"')\n\n\u002F\u002F 3. File miss → S3 GET. Bytes stored in file cache.\nawait ws.execute('cat \u002Fs3\u002Fdata\u002Flog.jsonl | wc -l')\n\n\u002F\u002F 4. File hit → 0 network calls.\nawait ws.execute('grep alert \u002Fs3\u002Fdata\u002Flog.jsonl')\n```\n\n## Contributors\n\nThanks to everyone who has contributed to Mirage.\n\n\u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fstrukto-ai\u002Fmirage\u002Fgraphs\u002Fcontributors\">\n  \u003Cimg src=\"https:\u002F\u002Fcontrib.rocks\u002Fimage?repo=strukto-ai\u002Fmirage\" alt=\"Mirage contributors\" \u002F>\n\u003C\u002Fa>\n","Mirage 是一个为AI代理设计的统一虚拟文件系统，它能够将S3、Google Drive、Slack、Gmail和Redis等不同服务和数据源整合到一个文件系统中。项目采用TypeScript开发，并支持Python接口，使得AI代理可以通过类似Unix的工具访问后端服务，实现跨服务的数据处理如同操作本地磁盘一样自然流畅。任何已经熟悉bash命令行语言的大规模语言模型都可以直接使用Mirage而无需额外学习新的命令词汇。适用于需要简化多源数据集成与处理流程的人工智能应用场景，如自动化文档管理、数据分析及信息检索等任务。",2,"2026-06-11 03:31:12","CREATED_QUERY"]