AgentFS: a SQLite-backed filesystem for AI agent state

The problem AgentFS targets: agent state scattered across tools

An agent that reads files, calls APIs and writes output typically leaves its state in three unrelated places: a working directory, an application database, and a log stream. Reconstructing what happened means joining them by timestamp and hoping the clocks agree. AgentFS's answer is to make one SQLite file the unit of agent state. The README states the whole runtime, meaning files, state and history, is stored in a single SQLite file, and that every file operation, tool call and state change is recorded in that database. The intended audience is therefore teams building agents who need to debug or reproduce a run, not teams looking for a faster local filesystem. The README frames the three benefits as auditability, reproducibility and portability, and the reproducibility example is deliberately unglamorous: copy the database with cp agent.db snapshot.db, then restore it later. That is the whole snapshot mechanism. There is no incremental backup format and no server to coordinate with. If your agent's value depends on knowing exactly which tool returned what at which second, this is the abstraction being sold.

Three interfaces over one SQLite file

AgentFS exposes three interfaces, according to the README: a POSIX-like filesystem for files and directories, a key-value store for agent state and context, and a toolcall audit trail for debugging and analysis. The SDK example shows all three on one object: agent.kv.set and agent.kv.get for state, agent.fs.writeFile and agent.fs.readdir for files, and agent.tools.record with a tool name, a start time, an end time, an input object and an output object. The storage layer is the agent filesystem described in SPEC.md, implemented using Turso. The CLI reads the same database and presents it three ways: agentfs fs for file operations, agentfs timeline for the action log, and agentfs mount for exposing the filesystem to the host. The timeline output in the README shows rows with an ID, a tool name, a status, a duration and a start time, including an entry with status error and a 300ms duration, so failures are first-class records rather than exceptions that vanish. Because everything lands in SQLite, the README's claim is that you can query the agent's complete history with SQL. That is the real differentiator: the audit trail is not a log file you grep, it is a table you join against.

Installing the AgentFS CLI and running a first filesystem

The README's install path for the CLI is a shell script served from the project's homepage domain. Run it, then initialize an agent filesystem with a name. The README shows the created path as .agentfs/my-agent.db and echoes back the agent ID.

curl -fsSL https://agentfs.ai/install | bash
agentfs init my-agent

After initialization, the CLI can list and read files through the agent. The README's example shows a single file named hello.txt and prints its contents. Note the prompt line beginning with "Using agent: my-agent", which tells you the CLI resolved the name to the database in .agentfs rather than a path you typed.

agentfs fs my-agent ls
agentfs fs my-agent cat hello.txt

The same commands accept a database path directly, which is useful when the file has been copied elsewhere. The README gives .agentfs/my-agent.db as that path in the example. To see the audit trail instead of the files, use the timeline subcommand; the README's output columns are ID, TOOL, STATUS, DURATION and STARTED.

agentfs fs .agentfs/my-agent.db cat hello.txt
agentfs timeline my-agent

For programmatic use, the SDK installs from npm as agentfs-sdk. The README's TypeScript example opens a persistent agent by id, which creates .agentfs/my-agent.db, or opens an ephemeral in-memory database when called with no arguments. That in-memory mode is worth noticing: it gives you the same three interfaces without a file on disk, which is convenient for tests but obviously discards the audit trail when the process exits.

Mounting AgentFS with FUSE on Linux and NFS on macOS

The CLI can expose an agent filesystem to the host so that ordinary programs read and write it. The README states that mounting uses FUSE on Linux and NFS on macOS, and the example mounts an agent at a local directory, writes a file through the mount point, and reads it back.

agentfs mount my-agent ./mnt
echo "hello" > ./mnt/hello.txt
cat ./mnt/hello.txt

There is also an experimental sandbox mode. The README shows agentfs run /bin/bash, which mounts the agent filesystem at /agent inside the sandbox and prints a welcome banner. Commands inside that shell write to /agent rather than the host filesystem.

agentfs run /bin/bash
echo "hello from agent" > /agent/hello.txt
cat /agent/hello.txt
exit

The repository layout supports the mount story: there is a sandbox directory alongside cli and sdk, and the examples directory contains a Firecracker example described as a minimal Firecracker VM with AgentFS mounted via NFSv3. Two caveats follow from the README's own wording. The sandbox is labelled experimental, so treat its isolation as a convenience rather than a security boundary. And the mount mechanism differs by platform, which means behaviour you observe on a Linux laptop is not automatically what a macOS developer sees.

Beta status, single-file state and where AgentFS is the wrong tool

The README carries a warning that the software is in beta, may contain bugs and unexpected behaviour, and advises caution with production data and backups. That is the project's own framing, and it should govern adoption decisions more than any feature list. The last push to the repository was on 2026-06-03, and the most recent release listed is v0.6.4 from 2026-03-25, with v0.6.3 on the same day and v0.6.2 a month earlier. Version numbering in the 0.6 range is consistent with the beta label; the project does not claim API stability. The second limitation is architectural. Concentrating files, key-value state and tool history in one SQLite file is what makes SQL queries and cp-based snapshots possible, but it also means that file is a single point of failure and a single unit of contention. An agent that writes large binary outputs will grow that database, and copying it for every snapshot duplicates the whole thing. The README's snapshot advice is literally cp, which does not scale to frequent checkpoints of a multi-gigabyte file. Finally, AgentFS is not a general-purpose filesystem. If your workload is a build system, a package cache or a database server's data directory, a normal filesystem or an overlay is the right answer; AgentFS is aimed at the state an agent produces, and the toolcall and key-value interfaces have no meaning outside that context. The README's FAQ section begins a comparison against Bubblewrap, but the text is truncated in the available README, so the project's own positioning against sandboxing tools cannot be quoted here.

AgentFS compared with Bubblewrap and plain sandboxing

The README's FAQ opens with "How is AgentFS different from X?" and names Bubblewrap as the first comparison, though the answer is cut off in the README text. The difference in approach is visible from what each tool is. Bubblewrap is a sandboxing utility that constructs a restricted mount namespace and then gets out of the way; it isolates a process but keeps no record of what that process did. AgentFS records file operations, key-value writes and tool calls in a queryable database, and its mount and sandbox features exist to route an agent's writes into that database. If your requirement is confinement, Bubblewrap addresses it directly and AgentFS's own README calls its sandbox experimental. If your requirement is a durable, inspectable trace of agent activity that you can snapshot and move between machines, Bubblewrap has nothing to offer and AgentFS is built for exactly that. The two are not mutually exclusive: a Firecracker example in the repository mounts AgentFS via NFSv3 inside a VM, which suggests the intended pattern is AgentFS for state and a separate mechanism for isolation.

Licence, upgrade cost and what to check before pinning a version

The repository's README badge points to the MIT licence and links to LICENSE.md in the repository root, and a licenses directory is present at the top level. The metadata supplied for this repository does not list a licence identifier, so the authoritative source is the file itself; read LICENSE.md and any files under licenses/ before you depend on the terms. Nothing here is legal advice, and the badge alone is not a substitute for the file. On upgrade cost, the README supports only a limited judgement: releases are tagged at 0.6.x, the README calls the software beta, and there is a CHANGELOG.md at the repository root. That changelog is the place to check before moving between versions, because a 0.x project is under no obligation to keep interfaces stable. The SDK is published to three ecosystems, crates.io as agentfs-sdk, npm as agentfs-sdk and PyPI as agentfs-sdk, so a version bump may need to be coordinated across whichever of those your agents use. Because the persisted format is a SQLite database defined by SPEC.md, an upgrade that changes the schema is the failure mode to watch for: a database written by an older release may not open cleanly under a newer one, and the README's backup advice is the mitigation it offers. Verify that by reading SPEC.md and the changelog rather than assuming forward compatibility.

Editorial conclusion

Adopt AgentFS if you need an auditable, snapshotable record of what an agent wrote and which tools it called, and you are willing to run beta software away from production data. Do not adopt it if you need a general-purpose POSIX filesystem or cannot tolerate a single SQLite file as the unit of state. Before committing, read SPEC.md and MANUAL.md, confirm the licence in the repository's LICENSE.md, and check the changelog for the version you plan to pin.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. tursodatabase/agentfs on GitHub