# agent-fs

> A sharable, searchable, persistent file system that any AI agent can use — via CLI or MCP.

agent-fs is a file system built for AI agents. It lets autonomous agents write, read,
search, comment on, and share files across systems — without human intervention.
Metadata is stored in SQLite and blobs in any S3-compatible storage, so it's
fully self-hostable.

## Quickstart

- Install: `bun add -g @desplega.ai/agent-fs`
- Onboard: `agent-fs onboard`
- Write: `agent-fs write hello.md --content "# Hello from an agent"`
- Claude Code skill: `npx skills add desplega-ai/agent-fs`

## Docs

- Homepage: https://agent-fs.dev
- Docs index: https://agent-fs.dev/docs
- Repository: https://github.com/desplega-ai/agent-fs
- Product overview: https://github.com/desplega-ai/agent-fs/blob/main/PRODUCT.md

### Getting started

- MCP setup: https://agent-fs.dev/docs/mcp-setup — connect agent-fs to Claude Code, Cursor, Codex, and other MCP clients
- Deployment: https://agent-fs.dev/docs/deployment — run locally, use remote S3, deploy services, and publish releases

### Reference

- API reference: https://agent-fs.dev/docs/api-reference — HTTP endpoints, auth, MCP transport, and operation dispatch
- SQL queries: https://agent-fs.dev/docs/sql — query CSV, Parquet, Excel, JSON, and SQLite documents with DuckDB
- OpenAPI spec: https://agent-fs.dev/docs/openapi.json

### Mounting (FUSE)

- Mounting overview: https://agent-fs.dev/docs/mounting — topologies, prerequisites, auth, and the remote mount flow
- FUSE mount: https://agent-fs.dev/docs/fuse-mount — mount an agent-fs drive as a Linux filesystem with open-to-close consistency
- FUSE compatibility: https://agent-fs.dev/docs/fuse-compat — sandbox and container runtime matrix for Linux FUSE support
- FUSE troubleshooting: https://agent-fs.dev/docs/fuse-troubleshooting — common mount errors, diagnosis order, and recovery commands
- Mounting on Sprite: https://agent-fs.dev/docs/mounting-sprite
- Mounting on E2B: https://agent-fs.dev/docs/mounting-e2b
- Mounting on Hetzner: https://agent-fs.dev/docs/mounting-hetzner

Every doc page is also available as raw markdown at the same path with a `.md` suffix
under `/docs/` (e.g. https://agent-fs.dev/docs/mcp-setup.md), suitable for agents that
prefer fetching markdown directly.

## Core commands

- `agent-fs write <path> --content '...'` — write a file (version-tracked)
- `agent-fs cat <path>` — read a file
- `agent-fs search '<query>'` — semantic search over stored files
- `agent-fs fts '<query>'` — full-text search over stored files
- `agent-fs sql "SELECT * FROM '/data/sales.csv'"` — DuckDB SQL over stored documents (csv, parquet, xlsx, json, sqlite)
- `agent-fs comment add <path> --content '...'` — leave a comment
- `agent-fs drive invite <email>` — share a drive with another agent or human

## Packages

- `@desplega.ai/agent-fs` — published CLI on npm
- Runs as a local daemon (HTTP API) or against a remote server
- MCP server included for Claude Code / Codex / any MCP-compatible client