Development
Plugin
mirage
The World's First Unified Virtual Filesystem For AI Agents
Plugin Signal68/100Solid
maintained100
capable23
documented75
adopted75
Install
$ npx -y skills add strukto-ai/mirage --agent claude-code
Run the curl in your terminal, the rest in Claude Code.
Stats
3,395
Stars
251
Forks
Active
Maintenance
TypeScript
Language
Apache-2.0
License
56m ago
Last commit
3mo ago
Created
Repo: strukto-ai/mirage
What's inside
MCP
1Badges
14
README
1Mirage is a Unified Virtual File System for AI Agents: it mounts services and data sources like S3, Google Drive, Slack, Gmail, and Redis side-by-side as one filesystem. Any LLM that already knows bash can read, grep, and pipe across every backend out of the box, with zero new vocabulary.
const ws = new Workspace({
'/data': new RAMResource(),
'/s3': new S3Resource({ bucket: 'logs' }),
'/slack': new SlackResource({ token: process.env.SLACK_BOT_TOKEN! }),
})
await ws.execute('grep -r alert /slack/channels/general__C04QX/ | wc -l')
await ws.execute('cp /s3/report.csv /data/local.csv')
await ws.execute('wc -l $(find /s3/data -name "*.jsonl")')
// Commands are extensible: register new commands, or override one per
// resource + filetype. Mirage ships no filetype renderers, so a format
// like Parquet renders however you register it.
ws.command('summarize', ...)
ws.command('cat', { resource: 's3', filetype: 'parquet' }, ...)
await ws.execute('summarize /data/local.csv')
await ws.execute('cat /s3/events/2026-05-06.parquet | jq .user')
About
- One interface instead of N SDKs and M MCPs. Every service speaks the same filesystem semantics, and pipelines compose across services as naturally as on a local disk.
- Around 50 built-in backends: RAM, Disk, Redis, S3 / R2 / OCI / Supabase / GCS, Gmail / GDrive / GDocs / GSheets / GSlides, GitHub / Linear / Notion / Trello, Slack / Discord / Email, MongoDB / GridFS / Postgres / LanceDB / Qdrant, SSH, and more, mounted side-by-side under a single root.
- Portable workspaces: clone, snapshot, and version a workspace; agent runs move between machines without restarting or reconfiguring the system.
- Embeddable: the Python and TypeScript SDKs run in-process inside FastAPI, Express, browser apps, or any async runtime; no separate process required.
- Agent integrations: OpenAI Agents SDK, Vercel AI SDK, LangChain, Pydantic AI, CAMEL, and OpenHands via the SDKs; coding agents through native adapters, installable plugins, MCP, or FUSE.
Architecture
Installation
- Python ≥ 3.11 for the
mirage-aipackage and themirageCLI - Node.js ≥ 20 for the TypeScript SDK
- macOS or Linux (FUSE-based mounts require platform support)
Python
uv add mirage-ai # installs the `mirage` library and the `mirage` CLI binary
TypeScript
npm install @struktoai/mirage-node # Node.js servers and CLIs
npm install @struktoai/mirage-browser # browser / edge runtimes
npm install @struktoai/mirage-agents # OpenAI / Vercel AI / LangChain / Mastra adapters
Both runtime packages pull in @struktoai/mirage-core automatically.
CLI
curl -fsSL https://strukto.ai/mirage/install.sh | sh
# or
npm install -g @struktoai/mirage-cli
# or
uvx mirage-ai
# or
npx @struktoai/mirage-cli
Quickstart
Python
from mirage import Workspace
from mirage.resource.ram import RAMResource
from mirage.resource.s3 import S3Config, S3Resource
ws = Workspace({
"/data": RAMResource(),
"/s3": S3Resource(S3Config(bucket="my-bucket")),
})
await ws.execute("cp /s3/report.csv /data/report.csv")
await ws.execute("grep alert /s3/data/log.jsonl | wc -l")
await ws.snapshot("demo.tar")
TypeScript
import { Workspace, RAMResource, S3Resource } from '@struktoai/mirage-node'
const ws = new Workspace({
'/data': new RAMResource(),
'/s3': new S3Resource({ bucket: 'my-bucket' }),
})
await ws.execute('cp /s3/report.csv /data/report.csv')
await ws.execute('grep alert /s3/data/log.jsonl | wc -l')
await ws.snapshot('demo.tar')
CLI
mirage workspace create ws.yaml --id demo
mirage execute --workspace_id demo --command "cp /s3/report.csv /data/report.csv"
mirage provision --workspace_id demo --command "cat /s3/data/large.jsonl"
mirage workspace snapshot demo demo.tar
mirage workspace load demo.tar --id demo-restored
Agent Frameworks
Mirage plugs into agent frameworks as a sandbox or tool layer. POSIX operations such as read can also be customized per resource and filetype, e.g. reading a PDF returns parsed pages instead of raw bytes.
| Integrations | |
|---|---|
| Python | OpenAI Agents SDK, LangChain, Pydantic AI, CAMEL, OpenHands, Agno |
| TypeScript | Vercel AI SDK, OpenAI Agents SDK, LangChain, Mastra |
| Coding agents | Claude Code, Codex, Grok Build, OpenCode, Pi |
Cache
Every Workspace has a two-layer cache so repeated work against remote backends hits local state instead of the network:
- Index cache: listings and metadata. The first directory walk hits the API; later ones serve from the index until the TTL expires (default 10 minutes).
- File cache: object bytes. The first read streams from origin; later pipelines read from cache (default 512 MB).
Both layers default to in-process RAM with zero setup. A Redis store shares cache state across workers, processes, and machines:
import { RedisFileCacheStore, S3Resource, Workspace } from '@struktoai/mirage-node'
const ws = new Workspace(
{ '/s3': new S3Resource({ bucket: 'my-bucket' }) },
{
cache: new RedisFileCacheStore({ url: 'redis://localhost:6379/0', cacheLimit: '8GB' }),
index: { type: 'redis', url: 'redis://localhost:6379/0', ttl: 600 },
},
)
See the cache docs for the full miss/hit lifecycle.
Contributors
Thanks to everyone who has contributed to Mirage.
File tree
1602strukto-ai/mirageView on GitHub
.agents/
plugins/
marketplace.json
.dockerignore
.env.example
.github/
actions/
integ-battery-setup/
action.yml
CODEOWNERS
dependabot.yml
ISSUE_TEMPLATE/
report.yml
workflows/
pre-commit.yml
test_cli.yml
test_install.yml
test_integ.yml
test_python.yml
test_typescript.yml
.gitignore
.isort.cfg
.pre-commit-config.yaml
AGENTS.md
assets/
mirage-arch-dark.svg
mirage-arch-light.svg
mirage-og-dark.png
mirage-og-dark@2x.png
mirage-og-light.png
mirage-og-light@2x.png
CITATION.cff
CLAUDE.md
conformance/
cases/
cat.json
cmp.json
du.json
file.json
find.json
grep.json
head.json
ls.json
md5.json
sort.json
stat.json
tree.json
wc.json
README.md
seeds.json
CONTRIBUTING.md
data/
example.feather
example.h5
example.json
example.jsonl
example.orc
example.parquet
example.pdf
example.xlsx
docker/
sandbox/
Dockerfile
docs/
.mintignore
docs.json
favicon.svg
home/
architecture.mdx
auth.mdx
bash.mdx
cache.mdx
cli.mdx
install.mdx
introduction.mdx
observer.mdx
policy-engine.mdx
python.mdx
resource-matrix.mdx
setup/
aliyun.mdx
backblaze.mdx
box.mdx
ceph.mdx
chroma.mdx
databricks.mdx
dify.mdx
digitalocean.mdx
discord.mdx
dropbox.mdx
email.mdx
fuse.mdx
gcs.mdx
github_ci.mdx
github.mdx
google.mdx
gridfs.mdx
hf_buckets.mdx
hf_datasets.mdx
hf_models.mdx
hf_spaces.mdx
lancedb.mdx
langfuse.mdx
linear.mdx
linux.mdx
macos.mdx
mem0.mdx
minio.mdx
mongodb.mdx
nextcloud.mdx
notion.mdx
oci.mdx
onedrive.mdx
postgres.mdx
qdrant.mdx
qingstor.mdx
r2.mdx
s3.mdx
scaleway.mdx
seaweedfs.mdx
sharepoint.mdx
slack.mdx
supabase.mdx
tencent.mdx
trello.mdx
wasabi.mdx
windows.mdx
snapshot.mdx
troubleshooting.mdx
images/
agno-logo.svg
aliyun-logo.svg
arm.svg
backblaze-logo.svg
camel-logo.svg
ceph-logo.svg
claude-logo.svg
demo-linear-issue.png
demo-slack-message.png
dify-logo.svg
digitalocean-logo.svg
huggingface-logo.svg
langchain-logo.svg
mem0.svg
minio-logo.svg
mirage-arch-dark.svg
mirage-arch-light.svg
mirage-icon-dark.svg
mirage-icon-light.svg
mirage-icon.svg
mirage-text-logo-dark.svg
mirage-text-logo-light.svg
mirage-text-logo.svg
openai-logo.svg
opencode-logo.svg
openhands-logo.svg
pi-logo.svg
pydantic-logo.svg
python-logo.svg
scaleway-logo.svg
seaweedfs-logo.svg
tencent-logo.svg
typescript-logo.svg
wasabi-logo.svg
logo/
dark.svg
light.svg
python/
agents/
agno.mdx
camel.mdx
claude-agent-sdk.mdx
claude-code.mdx
codex.mdx
grok-build.mdx
index.mdx
langchain.mdx
openai-agents.mdx
openhands.mdx
pydantic-ai.mdx
cli/
discord.mdx
git.mdx
gws.mdx
himalaya.mdx
index.mdx
linear.mdx
ntn.mdx
slack.mdx
install.mdx
quickstart.mdx
resource/
aliyun.mdx
backblaze.mdx
box.mdx
ceph.mdx
chroma.mdx
databricks_volume.mdx
dify.mdx
digitalocean.mdx
discord.mdx
disk.mdx
dropbox.mdx
email.mdx
gcs.mdx
gdocs.mdx
gdrive.mdx
github_ci.mdx
github.mdx
gmail.mdx
gridfs.mdx
gsheets.mdx
gslides.mdx
hf_buckets.mdx
hf_datasets.mdx
hf_models.mdx
hf_spaces.mdx
index.mdx
lancedb.mdx
langfuse.mdx
linear.mdx
mem0.mdx
minio.mdx
mongodb.mdx
new.mdx
nextcloud.mdx
notion.mdx
oci.mdx
onedrive.mdx
postgres.mdx
qdrant.mdx
qingstor.mdx
r2.mdx
ram.mdx
redis.mdx
s3.mdx
scaleway.mdx
seaweedfs.mdx
sharepoint.mdx
slack.mdx
ssh.mdx
supabase.mdx
tencent.mdx
trello.mdx
wasabi.mdx
runtime/
javascript.mdx
python.mdx
sandbox.mdx
setup/
chroma.mdx
databricks.mdx
dify.mdx
discord.mdx
email.mdx
fuse.mdx
github_ci.mdx
github.mdx
google.mdx
lancedb.mdx
langfuse.mdx
linear.mdx
mem0.mdx
mongodb.mdx
notion.mdx
onedrive.mdx
qdrant.mdx
slack.mdx
trello.mdx
watch-matrix.mdx
watch.mdx
snippets/
split-card.jsx
typescript/
agents/
claude-agent-sdk.mdx
claude-code.mdx
codex.mdx
grok-build.mdx
index.mdx
langchain.mdx
mastra.mdx
openai.mdx
opencode.mdx
pi.mdx
vercel.mdx
box.mdx
cli/
discord.mdx
git.mdx
gws.mdx
himalaya.mdx
index.mdx
linear.mdx
ntn.mdx
slack.mdx
discord.mdx
dropbox.mdx
install.mdx
limitations.mdx
python-fs.mdx
python.mdx
quickstart.mdx
runtime/
javascript.mdx
python.mdx
sandbox.mdx
server-and-cli.mdx
setup/
aliyun.mdx
backblaze.mdx
ceph.mdx
chroma.mdx
databricks_volume.mdx
digitalocean.mdx
disk.mdx
email.mdx
fuse.mdx
gcs.mdx
gdocs.mdx
gdrive.mdx
github_ci.mdx
github.mdx
gmail.mdx
gridfs.mdx
gsheets.mdx
gslides.mdx
hf_buckets.mdx
hf_datasets.mdx
hf_models.mdx
hf_spaces.mdx
lancedb.mdx
langfuse.mdx
linear.mdx
mem0.mdx
minio.mdx
mongodb.mdx
notion.mdx
oci.mdx
onedrive.mdx
opfs.mdx
postgres.mdx
qdrant.mdx
qingstor.mdx
r2.mdx
redis.mdx
s3.mdx
scaleway.mdx
seaweedfs.mdx
sharepoint.mdx
ssh.mdx
supabase.mdx
tencent.mdx
trello.mdx
wasabi.mdx
slack.mdx
watch-matrix.mdx
watch.mdx
examples/
python/
agents/
agno/
agno_example.py
camel/
sandbox_agent.py
claude_agent_sdk/
all_tools.py
langchain/
databricks_volume_deepagent.py
ram_pdf_deepagent.py
s3_deepagent.py
openai_agents/
multimodal_agent.py
ram_agent.py
sandbox_agent.py
slack_vision_agent.py
openhands/
README.md
sandbox_agent.py
pydantic_ai/
s3_agent.py
s3_pdf_agent.py
slack_pdf_agent.py
aliyun/
aliyun.py
backblaze/
backblaze.py
ceph/
ceph.py
chroma/
chroma_vfs.py
chroma.py
claude/
claude-memory.py
claude-sdk.py
cross/
cross_fuse.py
example.py
load_check.py
README.md
... 1600 moreShowing a partial view of a very large repo.
FAQ
mirage is a Claude Code plugin with 1 hand-picked skill for development work, indexed on Flowy. Install it with the command on its page. It includes mirage-filesystem. Its skills do not fire on their own yet. Request auto-invocation to have Flowy route them as you prompt. Free and open source.
- What is mirage?
- The World's First Unified Virtual Filesystem For AI Agents
- How do I install mirage?
- Run these in Claude Code: npx -y skills add strukto-ai/mirage --agent claude-code. Then prompt normally.
- Does mirage auto-invoke its skills?
- Not yet. It is indexed on Flowy as a plain plugin. Request auto-invocation on its page and Flowy will route its skills for you as you prompt.
- Is mirage free?
- Yes. Flowy is free and open source, with nothing gated. You can read every skill in full before you install.