\n A persistent, searchable filesystem for AI agents. \n Built by desplega.sh — by builders, for builders.\n
\n\n---\n\nAgent FS gives AI agents a structured filesystem with built-in semantic search, versioning, and identity management. It runs as a CLI and an HTTP server with integrated MCP support — so any AI coding assistant can use it as a long-term memory and file store.\n\nagent-fs was built to power the shared filesystem in [agent-swarm](https://github.com/desplega-ai/agent-swarm) — a multi-agent coordination framework. While it was designed for swarm agents to share files, search content, and collaborate, it works as a standalone filesystem for any AI agent.\n\n## Key Features\n\n- **Semantic search** — Index and search files using vector embeddings (OpenAI, Google GenAI, or local llama.cpp)\n- **SQL queries** — Run sandboxed DuckDB SQL over stored documents (CSV, TSV, Parquet, Excel, JSON, NDJSON, SQLite, DuckDB) — see [docs/sql.md](./docs/sql.md)\n- **Structured storage** — SQLite-backed file operations with metadata and versioning\n- **S3-compatible sync** — Sync agent workspaces to any S3-compatible object store\n- **Identity management** — Persistent agent identity files that evolve over time\n- **MCP integration** — Expose filesystem operations as MCP tools for Claude Code, Codex, and other assistants\n- **HTTP API** — RESTful server powered by Hono for programmatic access\n- **CLI** — Single binary (`agent-fs`) for local use and scripting\n\n## Quick Start\n\n### Install\n\nRequires [Bun](https://bun.sh) >= 1.4.0.\n\n```bash\nbun add -g @desplega.ai/agent-fs\n```\n\nOr build from source:\n\n```bash\ngit clone https://github.com/desplega-ai/agent-fs.git\ncd agent-fs\nbun install\nbun run build\n```\n\n### Usage\n\n```bash\n# Show available commands\nagent-fs --help\n```\n\n## Architecture\n\nAgent FS is a Bun monorepo with four packages:\n\n| Package | Description |\n|---------|-------------|\n| `@desplega.ai/agent-fs-core` | Core library — storage engine, semantic search, identity, S3 sync |\n| `@desplega.ai/agent-fs` | CLI binary (`agent-fs`) |\n| `@desplega.ai/agent-fs-mcp` | MCP stdio proxy + tool registration for the HTTP server |\n| `@desplega.ai/agent-fs-server` | HTTP server — RESTful API powered by Hono |\n\n## FUSE mount (Linux)\n\nagent-fs can expose your drives as a Linux FUSE filesystem so agents can use plain shell verbs (`cat`, `grep`, `mv`, `rm`) against agent-fs content.\n\n```bash\n# Linux only — the FUSE helper sub-package auto-installs via optionalDependencies.\n# Use Bun's installer; stock Ubuntu/Debian Node (18.x) chokes on a dep's\n# postinstall and aborts the global install.\nbun install -g @desplega.ai/agent-fs\nagent-fs daemon start\nagent-fs mount /mnt/agent-fs\n```\n\n**Requirements**\n\n- Linux x86_64 or aarch64. macOS and Windows are not supported (FUSE is a Linux kernel feature here).\n- `/dev/fuse` must be accessible. In Docker, run with `--cap-add SYS_ADMIN --device /dev/fuse`.\n- Sandboxes that use gVisor (GKE Sandbox, Cloud Run gen1), GitHub Codespaces, Modal sandboxes, or Fly.io Machines cannot mount FUSE — fall back to the CLI/MCP path.\n\n**Local-dev escape hatch (`AGENT_FS_FUSE_BIN`)**\n\nIf you're building the helper from source (e.g. macOS dev host or a custom Linux build), point the CLI at your local binary:\n\n```bash\ncd packages/fuse-helper && cargo build --release\nexport AGENT_FS_FUSE_BIN=\"$PWD/target/release/agent-fs-fuse\"\nagent-fs mount /tmp/m\n```\n\n`AGENT_FS_FUSE_BIN` takes precedence over the auto-resolved sub-package binary.\n\n**Remote mount (`--remote`)**\n\nWhen your agents run inside a sandbox that can't host a local daemon (Sprite, E2B, ephemeral CI runners), point the mount at a remote agent-fs HTTP API instead of a local Unix socket:\n\n```bash\nagent-fs mount /mnt/agent-fs --remote \\\n --api-url https://my-agent-fs.example.com \\\n --api-key \"$AGENT_FS_API_KEY\"\n```\n\nThe helper talks to the remote API directly — no local daemon, no S3 credentials in the sandbox. End-to-end coverage for this topology lives at `scripts/e2e-remote-mount.ts`:\n\n```bash\n# Spins up MinIO, a host-side daemon, and a Docker container with fuse3.\n# Mounts via --remote against the daemon's HTTP API and exercises ~8 ops.\n# Requires Docker Desktop / OrbStack on Mac.\nbun run scripts/e2e-remote-mount.ts\n```\n\n**macOS testing harness**\n\nmacOS can build the helper but not mount it. Use the Docker harness to test mount behaviour from a Mac host:\n\n```bash\nbash packages/fuse-helper/docker/run-mount-test.sh\n```\n\n**Per-environment guides**\n\nSee [`docs/mounting/`](./docs/mounting/README.md) for the general overview plus step-by-step guides for [Sprite](./docs/mounting/sprite.md), [E2B](./docs/mounting/e2b.md), and [Hetzner Cloud](./docs/mounting/hetzner.md). Existing FUSE references — [`fuse-mount.md`](./docs/fuse-mount.md), [`fuse-compat.md`](./docs/fuse-compat.md), [`fuse-troubleshooting.md`](./docs/fuse-troubleshooting.md) — cover mount semantics, sandbox compatibility, and the full error catalogue.\n\n## Documentation\n\n- [Mounting Guides](./docs/mounting/README.md) — General overview + per-env guides (Sprite, E2B, Hetzner)\n- [MCP Setup Guide](./docs/mcp-setup.md) — Connect agent-fs to Claude Code, Cursor, or any MCP client\n- [Deployment Guide](./docs/deployment.md) — Local, remote S3, team, and multi-agent deployments\n- [API Reference](./docs/api-reference.md) — HTTP API and OpenAPI spec\n\n## Development\n\n```bash\nbun install # Install dependencies\nbun run typecheck # Type checking\nbun run test # Run tests\nbun run build # Bundle CLI for npm\n```\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for the full development guide.\n\n## Releasing\n\nReleases are automatic — a version change landing on `main` tags and publishes.\n\n```bash\n./scripts/release.sh 0.13.0\n```\n\nSee [RELEASING.md](./RELEASING.md) for the full process, version-sync rules, and recovery steps.\n\n## Deploy to Fly.io\n\nDeploy a persistent agent-fs instance to [Fly.io](https://fly.io) with Tigris S3 storage:\n\n```bash\ngit clone https://github.com/desplega-ai/agent-fs && cd agent-fs\nbun run scripts/fly-deploy.ts\n```\n\nSee [DEPLOYMENT.md](./DEPLOYMENT.md) for Docker, BYOK storage, and manual setup options.\n\n## Live Viewer\n\n**[live.agent-fs.dev](https://live.agent-fs.dev)** — A stateless browser UI (local storage only) for inspecting any agent-fs deployment. Point it at your server URL to browse files and search content — nothing is stored server-side.\n\nSearch covers the selected drive. Files matches filename patterns across all directories.\nFull-text treats input as literal terms, so `ai-tinkerers` needs no query-language quoting in the UI.\nHybrid combines keywords and meaning. Semantic requires an embedding provider.\nThe UI distinguishes request errors, provider hints, and successful searches with no matches.\nAn open file outside the results carries a separate label.\n\nThe CLI and MCP `fts` operation retain raw FTS5 syntax. Use `agent-fs fts '\"ai-tinkerers\"'` for a punctuation-bearing term.\n\n## Contributing\n\nWe welcome contributions! Whether it's bug reports, feature requests, docs improvements, or code — all are welcome.\n\n1. Fork the repo\n2. Create a branch (`git checkout -b my-feature`)\n3. Make your changes\n4. Open a PR\n\nJoin our [Discord](https://discord.gg/KZgfyyDVZa) if you have questions or want to discuss ideas.\n\n## License\n\n[MIT](./LICENSE) — 2025-2026 [desplega.ai](https://desplega.ai)\n","readmeFilename":"README.md"}
![\"GitHub](\"https://img.shields.io/github/stars/desplega-ai/agent-fs?style=flat-square&color=yellow\")
\n ![\"MIT](\"https://img.shields.io/github/license/desplega-ai/agent-fs?style=flat-square\")
\n ![\"PRs](\"https://img.shields.io/badge/PRs-welcome-brightgreen?style=flat-square\"){kind=icon}
\n ![\"Discord\"](\"https://img.shields.io/badge/Discord-Join%20us-5865F2?style=flat-square&logo=discord&logoColor=white\"){kind=icon}
\n