AgentFS
The filesystem for agents.
⚠️ Warning: This software is in BETA. It may still contain bugs and unexpected behavior. Use caution with production data and ensure you have backups.
🎯 What is AgentFS?
AgentFS is a filesystem explicitly designed for AI agents. Just as traditional filesystems provide file and directory abstractions for applications, AgentFS provides the storage abstractions that AI agents need.
The AgentFS repository consists of the following:
- SDK - TypeScript, Python, and Rust libraries for programmatic filesystem access.
- CLI - Command-line interface for managing agent filesystems:
- Mount AgentFS on host filesystem with FUSE on Linux and NFS on macOS.
- Access AgentFS files with a command line tool.
- AgentFS Specification - SQLite-based agent filesystem specification.
💡 Why AgentFS?
AgentFS provides the following benefits for agent state management:
- Auditability: Every file operation, tool call, and state change is recorded in a SQLite database file. Query your agent’s complete history with SQL to debug issues, analyze behavior, or meet compliance requirements.
- Reproducibility: Snapshot an agent’s state at any point with cp agent.db snapshot.db. Restore it later to reproduce exact execution states, test what-if scenarios, or roll back mistakes.
- Portability: The entire agent runtime—files, state, history —is stored in a single SQLite file. Move it between machines, check it into version control, or deploy it to any system where Turso runs.
Read more about the motivation for AgentFS in the announcement blog post.
🧑💻 Getting Started
Using the CLI
Install the AgentFS CLI:
curl -fsSL https://agentfs.ai/install | bash
Initialize an agent filesystem:
$ agentfs init my-agent
Created agent filesystem: .agentfs/my-agent.db
Agent ID: my-agent
Inspect the agent filesystem:
$ agentfs fs my-agent ls
Using agent: my-agent
f hello.txt
$ agentfs fs my-agent cat hello.txt
hello from agent
You can also use a database path directly:
$ agentfs fs .agentfs/my-agent.db cat hello.txt
hello from agent
View the agent’s action timeline:
$ agentfs timeline my-agent
ID TOOL STATUS DURATION STARTED
4 execute_code pending -- 2024-01-05 09:44:20
3 api_call error 300ms 2024-01-05 09:44:15
2 read_file success 50ms 2024-01-05 09:44:10
1 web_search success 1200ms 2024-01-05 09:43:45
You can mount an agent filesystem using FUSE (Linux) or NFS (macOS):
$ agentfs mount my-agent ./mnt
$ echo "hello" > ./mnt/hello.txt
$ cat ./mnt/hello.txt
hello
You can also run a program in an experimental sandbox with the agent filesystem mounted at /agent:
$ agentfs run /bin/bash
Welcome to AgentFS!
$ echo "hello from agent" > /agent/hello.txt
$ cat /agent/hello.txt
hello from agent
$ exit
Read the User Manual for complete documentation.
Using the SDK
Install the SDK in your project:
npm install agentfs-sdk
Use it in your agent code:
import { AgentFS } from 'agentfs-sdk';
// Persistent storage with identifier
const agent = await AgentFS.open({ id: 'my-agent' });
// Creates: .agentfs/my-agent.db
// Or use ephemeral in-memory database
const ephemeralAgent = await AgentFS.open();
// Key-value operations
await agent.kv.set('user:preferences', { theme: 'dark' });
const prefs = await agent.kv.get('user:preferences');
// Filesystem operations
await agent.fs.writeFile('/output/report.pdf', pdfBuffer);
const files = await agent.fs.readdir('/output');
// Tool call tracking
await agent.tools.record(
'web_search',
Date.now() / 1000,
Date.now() / 1000 + 1.5,
{ query: 'AI' },
{ results: [...] }
);
Examples
This source repository also contains examples that demonstrate how to integrate AgentFS with some popular AI frameworks:
- Mastra - Research assistant using the Mastra AI framework
- Claude Agent SDK - Research assistant using Anthropic’s Claude Agent SDK
- OpenAI Agents - Research assistant using OpenAI Agents SDK
- Firecracker - Minimal Firecracker VM with AgentFS mounted via NFSv3
- AI SDK + just-bash - Interactive AI agent using Vercel AI SDK with just-bash for command execution
- Cloudflare Workers - AI agent using AI SDK + just-bash on Cloudflare Workers with Durable Objects storage
See the examples directory for more details.
🔧 How AgentFS Works?
AgentFS is an agent filesystem accessible through an SDK that provides three essential interfaces for agent state management:
- Filesystem: A POSIX-like filesystem for files and directories
- Key-Value: A key-value store for agent state and context
- Toolcall: A toolcall audit trail for debugging and analysis
At the heart of AgentFS is the agent filesystem, a complete SQLite-based storage system for agents implemented using Turso. Everything an agent does—every file it creates, every piece of state it stores, every tool it invokes—lives in a single SQLite database file.
🤔 FAQ
How is AgentFS different from X?
Bubblewrap provides filesystem isolation using Linux namespaces and overlays. While you could achieve similar isolation with a bwrap call that mounts / read-only and uses --tmp-overlay on the working directory, the key difference is persistence and queryability: with AgentFS, the upper filesystem is stored in a single SQLite database file, which you can query, snapshot, and move to another machine. Read more about the motivation in the announcement blog post.
Docker Sandbox and AgentFS are complementary rather than competing. AgentFS answers “what happened and what’s the state?” while Docker Sandboxes answer “how do I run this safely?” You could use both together: run an agent inside a Docker Sandbox for security, while using AgentFS inside that sandbox for structured state management and audit trails.
Git worktrees let you check out multiple branches of a repository into separate directories, allowing agents to work on independent copies of the source code—similar to AgentFS. But AgentFS solves the problem at a lower level. With git worktrees, nothing prevents an agent from modifying files outside its worktree: another agent’s worktree, system files, or anything else on the filesystem. The isolation is purely conventional, not enforced. AgentFS provides filesystem-level copy-on-write isolation that’s system-wide and cannot be bypassed—letting you safely run untrusted agents. And because it operates below git, it also handles untracked files, making it useful beyond just version-controlled source code.
Why implement AgentFS at the filesystem layer instead of using containers or VMs?
The filesystem layer gives us capabilities that block devices can’t. First, because everything is stored in structured SQLite tables, you can query the filesystem, which is essential for auditability and debugging agent behavior. Second, SQLite’s write-ahead log enables snapshotting and time-travel forking by capturing every filesystem change. Third, we can provide an SDK that works in environments such as serverless or the browser, where there’s no way to mount a block device at all. Note that this approach works fine with containers and VMs too—you can use AgentFS via remote filesystem protocols like NFS or through mechanisms like virtio-fuse.
📚 Learn More
Blog Posts
📝 License
MIT
评论