{ "markdown": "

\n \"GitHub\n \"MIT\n \"PRs\n \"Discord\"\n

\n\n

\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\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", "bytes": 7601, "sha": "7a36e844c4b4230d458f9b76c1529de97a08e172bd75ef607790f577530fb46e", "repo_slug": "desplega-ai/agent-fs", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/skl_desplega_ai_agent_fs_agent_fs_bc366abc/readme" }