The Filesystem for Agents

3 hours ago 1

The filesystem for agents

⚠️ Warning: This software is ALPHA; use only for development, testing, and experimentation. We are working to make it production-ready, but do not use it for critical data until it is ready.

AgentFS is a filesystem designed specifically for AI agents. Just as traditional filesystems provide file and directory abstractions for applications, AgentFS provides the storage abstractions that AI agents need.

At the heart of AgentFS is the agent filesystem - a complete SQLite-based storage system for agents implemented using Turso. It combines three essential components: a POSIX-like virtual filesystem for files and directories, a key-value store for agent state and context, and an audit trail tool for debugging and analysis. 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.

AgentFS provides four main components:

CLI - Command-line interface for managing agents
SDK - TypeScript and Rust libraries for programmatic access
Sandbox - Linux-compatible execution environment
Specification - SQLite-based filesystem architecture

Initialize an agent filesystem:

$ agentfs init Created agent filesystem: agent.db

Run a program in the 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

Inspect the agent filesystem from outside:

$ agentfs fs ls f hello.txt $ agentfs fs cat hello.txt hello from agent

Read the User Manual for complete documentation.

Install the SDK in your project:

Use it in your agent code:

import { AgentFS } from 'agentfs-sdk'; const agent = new AgentFS('./agent.db'); // 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: [...] } );

See the SDK documentation in MANUAL.md and examples for more details.

Auditability: Every file operation, tool call, and state change is recorded in SQLite. 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.

Simplicity: No configuration files, no database servers, no distributed systems. Just a single file and a simple API.

Sandboxing: Run agents in an isolated Linux environment where filesystem access is controlled and monitored. Perfect for testing untrusted code or enforcing security policies.

User Manual - Complete guide to using the AgentFS CLI and SDK
Agent Filesystem Specification - Technical specification of the SQLite schema
SDK Examples - Working code examples
Turso database - an in-process SQL database, compatible with SQLite.

MIT

Read Entire Article

The Filesystem for Agents

Related

Neuraxon – A New Neural Growth and Computation Blueprint

Agile and Coding: Please don't break things

How to Make a Great Hackathon