How penberg/agentfs works
1. Repository purpose and core architecture
AgentFS is a polyglot system centered on a single storage model: an agent’s state lives in a SQLite database file. Everything else in the repo—CLI, SDKs, sandboxing, and examples—either reads/writes that database directly or exposes it through filesystem-like interfaces.
2. Canonical storage boundary
The key architectural boundary is the AgentFS specification in SPEC.md: a SQLite-backed schema that stores three main kinds of state:
filesystem contents, key-value state, and toolcall history. This makes the database the source of truth for persistence, auditability, and snapshotting.
3. CLI as the operational interface
The Rust cli/ crate is the main end-user entrypoint. It provides commands for initializing databases, inspecting files, querying timelines, mounting the filesystem, syncing, running programs in a sandbox, and serving or migrating data. In diagram terms, the CLI is the control plane around the SQLite-backed agent filesystem.
4. Filesystem exposure paths
The CLI exposes AgentFS as a mounted filesystem through platform-specific mechanisms:
Linux uses FUSE, while macOS uses NFS. The tree shows separate mount and NFS modules, plus platform-specific run_* implementations. This is a major boundary: the same storage is accessed either as a mounted filesystem or via direct command-line operations.
5. Low-level filesystem plumbing
The cli/src/fuser/ subtree implements FUSE protocol handling, request/response wiring, deferred notifications, and session management. This is infrastructure code that adapts AgentFS’s virtual filesystem semantics to kernel-facing mount protocols on supported platforms.
6. NFS server path
The cli/src/nfsserve/ subtree implements a full NFS server stack: RPC, XDR, portmap, mount handling, permissions, transport, and VFS translation. This is the macOS-friendly mount path and a second major integration boundary between the SQLite-backed store and host filesystems.
7. Sandbox/runtime isolation
The cli/src/sandbox/ modules implement platform-specific sandbox execution, including Linux ptrace-related logic and Darwin support. The sandboxed run command uses AgentFS as the mounted working state for a program, so the runtime boundary is: host process executes inside a constrained environment while its filesystem state is persisted in AgentFS.
8. SDKs as direct programmatic access
The sdk/ directory contains Rust, Python, and TypeScript libraries that speak the AgentFS schema directly. They expose the same conceptual primitives—filesystem, key-value store, and toolcalls—without requiring a mount. This is the main API boundary for agent applications and frameworks.
9. SDK runtime adaptation
Each SDK adapts AgentFS to its host runtime:
Rust has native filesystem, overlay, and connection-pool modules;
TypeScript splits into Node, browser, and integration layers;
Python packages the same abstractions for application code;
Go appears as an auxiliary SDK with tests and benchmarks.
The important architectural point is that all SDKs target the same storage model but optimize for different execution environments.
10. Overlay and host filesystem behavior
The Rust and Go SDKs contain overlay/host filesystem abstractions, indicating support for copy-on-write semantics and host-backed layers. This matters because AgentFS is not just a flat key-value store; it can model mutable filesystem behavior on top of persistent state.
11. Examples as integration patterns
The examples/ tree demonstrates how AgentFS is embedded into real agent stacks: Claude Agent SDK, OpenAI Agents, Mastra, Cloudflare Workers, AI SDK + just-bash, and Firecracker. These examples show the intended architecture pattern: an agent framework or runtime uses AgentFS for durable agent state while application logic remains framework-specific.
12. Storage and deployment variants
The repo supports multiple deployment contexts:
local disk SQLite files,
browser/serverless-friendly SDK usage,
Cloudflare Durable Objects in the Workers example,
and VM-based execution in the Firecracker example.
This makes AgentFS a portability layer, not a single deployment target.
13. Validation and compatibility surface
The Rust CLI has extensive syscall and mount tests, while the SDKs have unit and spec tests. The repo also has CI workflows for Rust, TypeScript, and Python. Architecturally, this indicates that protocol compatibility and filesystem semantics are critical to the project’s correctness.
14. How to draw the system
A useful diagram should place the SQLite AgentFS database at the center, with four major outward paths:
the Rust CLI for human/ops workflows,
FUSE/NFS mount layers for host filesystem access,
the SDKs for embedded programmatic access,
and example agent applications that consume those SDKs.
The sandbox and overlay components sit between execution runtimes and the central store, enforcing isolation and copy-on-write behavior.
Main entry points: SPEC.md AgentFS spec · agentfs.ts TypeScript SDK · cmd/mod.rs Commands · mount/mod.rs Mount layer
Components 18
Storage model
Canonical SQLite-backed AgentFS specification and data model.
- AgentFS spec · Canonical storage model for filesystem contents, key-value state, and toolcall history.
SPEC.md
CLI runtime
Rust command-line control plane and filesystem integration layers.
- CLI · Primary user-facing entrypoint for init, inspect, mount, sync, run, serve, and migrate workflows.
cli/src/main.rs - Commands · Command router and operational subcommands for AgentFS management.
cli/src/cmd/mod.rs - FS ops · Init, filesystem inspection, timeline, sync, ps, completions, and migration-facing command logic.
cli/src/cmd/fs.rs - Mount layer · Platform-facing filesystem exposure through mount orchestration and backend selection.
cli/src/mount/mod.rs - FUSE stack · Linux mount plumbing that translates AgentFS semantics into FUSE requests and replies.
cli/src/fuser/mod.rs - NFS server · macOS-friendly NFS server stack including RPC, portmap, mount, permissions, and VFS translation.
cli/src/nfsserve/mod.rs
SDKs
Language bindings that access the AgentFS schema directly.
- Rust SDK · Native Rust access layer for filesystem, key-value, toolcalls, and overlay/host filesystem behavior.
sdk/rust/src/lib.rs - TypeScript SDK · Node, browser, and integration-oriented TypeScript API for AgentFS primitives.
sdk/typescript/src/agentfs.ts - Python SDK · Python package exposing direct AgentFS filesystem, kvstore, and toolcall access.
sdk/python/agentfs_sdk/agentfs.py - Go SDK · Go implementation of the AgentFS client and overlay filesystem abstractions.
sdk/go/agentfs.go
Examples
Agent and deployment integrations built on top of the SDKs.
- Claude app · Research-assistant example integrating AgentFS with Claude-style agent workflows.
examples/claude-agent/research-assistant/src/agent.ts - OpenAI app · Research-assistant example using AgentFS with OpenAI Agents tooling.
examples/openai-agents/research-assistant/src/agent.ts - Mastra app · Research-assistant example using AgentFS inside a Mastra workflow stack.
examples/mastra/research-assistant/src/mastra/index.ts - Cloudflare app · Workers-based example showing AgentFS in a serverless deployment context.
examples/cloudflare/src/index.ts - Firecracker app · VM-based deployment example demonstrating isolated execution around AgentFS.
examples/firecracker/firecracker.sh
Sandbox
Execution isolation and virtual filesystem layers for running programs against AgentFS.
Connections 23
- CLI → Commands: dispatches · Main binary delegates to the subcommand router.
- Commands → FS ops: includes · Filesystem-oriented operational commands are grouped under the CLI command set.
- Commands → Mount layer: includes · Mount-related commands are grouped under the CLI command set.
- Commands → Sandbox: includes · Run/sandbox commands are routed through the CLI command set.
- Mount layer → FUSE stack: linux path · Linux mounts are handled through the FUSE bridge.
- Mount layer → NFS server: darwin path · macOS mounts are handled through the NFS server stack.
- FUSE stack → AgentFS spec: reads/writes · FUSE requests are translated against the AgentFS storage model.
- NFS server → AgentFS spec: reads/writes · NFS operations are translated against the AgentFS storage model.
- FS ops → AgentFS spec: operates on · Init, inspect, timeline, sync, and migrate commands work on the canonical database.
- Sandbox → VFS core: executes in · Sandbox commands use the sandbox virtual filesystem and syscall layers.
- VFS core → AgentFS spec: persists to · Sandbox state and filesystem mutations are backed by the SQLite source of truth.
- Rust SDK → AgentFS spec: implements · Rust bindings target the AgentFS schema directly.
- TypeScript SDK → AgentFS spec: implements · TypeScript bindings target the AgentFS schema directly.
- Python SDK → AgentFS spec: implements · Python bindings target the AgentFS schema directly.
- Go SDK → AgentFS spec: implements · Go bindings target the AgentFS schema directly.
- Rust SDK → VFS core: supports · Rust SDK includes host filesystem and overlay behavior relevant to sandboxed execution.
- TypeScript SDK → Claude app: used by · Claude research assistant example is built on the TypeScript SDK.
- TypeScript SDK → OpenAI app: used by · OpenAI agents example is built on the TypeScript SDK.
- TypeScript SDK → Mastra app: used by · Mastra example is built on the TypeScript SDK.
- TypeScript SDK → Cloudflare app: used by · Cloudflare example uses the TypeScript SDK and its serverless integration.
- TypeScript SDK → Firecracker app: used by · Firecracker example demonstrates deployment around the TypeScript SDK.
- Python SDK → Claude app: pattern · Python SDK represents the same direct-access architecture used by agent examples.
- AgentFS spec → CLI: centered on · The CLI is an operational interface around the canonical storage model.