# penberg/agentfs architecture

> Architecture diagram of the GitHub repository penberg/agentfs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/penberg/agentfs
- Repository: https://github.com/penberg/agentfs

## Overview

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`](https://github.com/penberg/agentfs/blob/main/SPEC.md) (AgentFS spec), [`sdk/typescript/src/agentfs.ts`](https://github.com/penberg/agentfs/blob/main/sdk/typescript/src/agentfs.ts) (TypeScript SDK), [`cli/src/cmd/mod.rs`](https://github.com/penberg/agentfs/blob/main/cli/src/cmd/mod.rs) (Commands), [`cli/src/mount/mod.rs`](https://github.com/penberg/agentfs/blob/main/cli/src/mount/mod.rs) (Mount layer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_spec["Storage model"]
  node_spec["AgentFS spec<br/>SQLite schema<br/>[SPEC.md]"]
end

subgraph group_group_cli["CLI runtime"]
  node_cli_main["CLI<br/>Rust command<br/>[main.rs]"]
  node_cli_cmds["Commands<br/>[mod.rs]"]
  node_cli_fs["FS ops<br/>filesystem commands<br/>[fs.rs]"]
  node_cli_mount["Mount layer<br/>mount adapters<br/>[mod.rs]"]
  node_cli_fuse["FUSE stack<br/>kernel FS bridge<br/>[mod.rs]"]
  node_cli_nfs["NFS server<br/>network FS bridge<br/>[mod.rs]"]
end

subgraph group_group_sdk["SDKs"]
  node_sdk_rust["Rust SDK<br/>[lib.rs]"]
  node_sdk_ts["TypeScript SDK<br/>[agentfs.ts]"]
  node_sdk_py["Python SDK<br/>[agentfs.py]"]
  node_sdk_go["Go SDK<br/>[agentfs.go]"]
end

subgraph group_group_examples["Examples"]
  node_ex_claude["Claude app<br/>agent example<br/>[agent.ts]"]
  node_ex_openai["OpenAI app<br/>agent example<br/>[agent.ts]"]
  node_ex_mastra["Mastra app<br/>agent example<br/>[index.ts]"]
  node_ex_cloudflare["Cloudflare app<br/>serverless example<br/>[index.ts]"]
  node_ex_firecracker["Firecracker app<br/>VM example<br/>[firecracker.sh]"]
end

subgraph group_group_sandbox["Sandbox"]
  node_cli_sandbox["Sandbox<br/>runtime isolation<br/>[mod.rs]"]
  node_sandbox_vfs["VFS core<br/>virtual fs<br/>[mod.rs]"]
end

node_cli_main -->|"dispatches"| node_cli_cmds
node_cli_cmds -->|"includes"| node_cli_fs
node_cli_cmds -->|"includes"| node_cli_mount
node_cli_cmds -->|"includes"| node_cli_sandbox
node_cli_mount -->|"linux path"| node_cli_fuse
node_cli_mount -->|"darwin path"| node_cli_nfs
node_cli_fuse -->|"reads/writes"| node_spec
node_cli_nfs -->|"reads/writes"| node_spec
node_cli_fs -->|"operates on"| node_spec
node_cli_sandbox -->|"executes in"| node_sandbox_vfs
node_sandbox_vfs -->|"persists to"| node_spec
node_sdk_rust -->|"implements"| node_spec
node_sdk_ts -->|"implements"| node_spec
node_sdk_py -->|"implements"| node_spec
node_sdk_go -->|"implements"| node_spec
node_sdk_rust -->|"supports"| node_sandbox_vfs
node_sdk_ts -->|"used by"| node_ex_claude
node_sdk_ts -->|"used by"| node_ex_openai
node_sdk_ts -->|"used by"| node_ex_mastra
node_sdk_ts -->|"used by"| node_ex_cloudflare
node_sdk_ts -->|"used by"| node_ex_firecracker
node_sdk_py -.->|"pattern"| node_ex_claude
node_spec -->|"centered on"| node_cli_main

click node_spec "https://github.com/penberg/agentfs/blob/main/SPEC.md"
click node_cli_main "https://github.com/penberg/agentfs/blob/main/cli/src/main.rs"
click node_cli_cmds "https://github.com/penberg/agentfs/blob/main/cli/src/cmd/mod.rs"
click node_cli_fs "https://github.com/penberg/agentfs/blob/main/cli/src/cmd/fs.rs"
click node_cli_mount "https://github.com/penberg/agentfs/blob/main/cli/src/mount/mod.rs"
click node_cli_fuse "https://github.com/penberg/agentfs/blob/main/cli/src/fuser/mod.rs"
click node_cli_nfs "https://github.com/penberg/agentfs/blob/main/cli/src/nfsserve/mod.rs"
click node_cli_sandbox "https://github.com/penberg/agentfs/blob/main/cli/src/sandbox/mod.rs"
click node_sandbox_vfs "https://github.com/penberg/agentfs/blob/main/sandbox/src/vfs/mod.rs"
click node_sdk_rust "https://github.com/penberg/agentfs/blob/main/sdk/rust/src/lib.rs"
click node_sdk_ts "https://github.com/penberg/agentfs/blob/main/sdk/typescript/src/agentfs.ts"
click node_sdk_py "https://github.com/penberg/agentfs/blob/main/sdk/python/agentfs_sdk/agentfs.py"
click node_sdk_go "https://github.com/penberg/agentfs/blob/main/sdk/go/agentfs.go"
click node_ex_claude "https://github.com/penberg/agentfs/blob/main/examples/claude-agent/research-assistant/src/agent.ts"
click node_ex_openai "https://github.com/penberg/agentfs/blob/main/examples/openai-agents/research-assistant/src/agent.ts"
click node_ex_mastra "https://github.com/penberg/agentfs/blob/main/examples/mastra/research-assistant/src/mastra/index.ts"
click node_ex_cloudflare "https://github.com/penberg/agentfs/blob/main/examples/cloudflare/src/index.ts"
click node_ex_firecracker "https://github.com/penberg/agentfs/blob/main/examples/firecracker/firecracker.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_spec toneBlue
class node_cli_main,node_cli_cmds,node_cli_fs,node_cli_mount,node_cli_fuse,node_cli_nfs toneAmber
class node_sdk_rust,node_sdk_ts,node_sdk_py,node_sdk_go toneMint
class node_ex_claude,node_ex_openai,node_ex_mastra,node_ex_cloudflare,node_ex_firecracker toneRose
class node_cli_sandbox,node_sandbox_vfs toneIndigo
```

## Components

### Storage model

Canonical SQLite-backed AgentFS specification and data model.

- [AgentFS spec](https://github.com/penberg/agentfs/blob/main/SPEC.md): SQLite schema · 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](https://github.com/penberg/agentfs/blob/main/cli/src/main.rs): Rust command · Primary user-facing entrypoint for init, inspect, mount, sync, run, serve, and migrate workflows. · `cli/src/main.rs`
- [Commands](https://github.com/penberg/agentfs/blob/main/cli/src/cmd/mod.rs): subcommands · Command router and operational subcommands for AgentFS management. · `cli/src/cmd/mod.rs`
- [FS ops](https://github.com/penberg/agentfs/blob/main/cli/src/cmd/fs.rs): filesystem commands · Init, filesystem inspection, timeline, sync, ps, completions, and migration-facing command logic. · `cli/src/cmd/fs.rs`
- [Mount layer](https://github.com/penberg/agentfs/blob/main/cli/src/mount/mod.rs): mount adapters · Platform-facing filesystem exposure through mount orchestration and backend selection. · `cli/src/mount/mod.rs`
- [FUSE stack](https://github.com/penberg/agentfs/blob/main/cli/src/fuser/mod.rs): kernel FS bridge · Linux mount plumbing that translates AgentFS semantics into FUSE requests and replies. · `cli/src/fuser/mod.rs`
- [NFS server](https://github.com/penberg/agentfs/blob/main/cli/src/nfsserve/mod.rs): network FS bridge · 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](https://github.com/penberg/agentfs/blob/main/sdk/rust/src/lib.rs): library · Native Rust access layer for filesystem, key-value, toolcalls, and overlay/host filesystem behavior. · `sdk/rust/src/lib.rs`
- [TypeScript SDK](https://github.com/penberg/agentfs/blob/main/sdk/typescript/src/agentfs.ts): library · Node, browser, and integration-oriented TypeScript API for AgentFS primitives. · `sdk/typescript/src/agentfs.ts`
- [Python SDK](https://github.com/penberg/agentfs/blob/main/sdk/python/agentfs_sdk/agentfs.py): library · Python package exposing direct AgentFS filesystem, kvstore, and toolcall access. · `sdk/python/agentfs_sdk/agentfs.py`
- [Go SDK](https://github.com/penberg/agentfs/blob/main/sdk/go/agentfs.go): library · 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](https://github.com/penberg/agentfs/blob/main/examples/claude-agent/research-assistant/src/agent.ts): agent example · Research-assistant example integrating AgentFS with Claude-style agent workflows. · `examples/claude-agent/research-assistant/src/agent.ts`
- [OpenAI app](https://github.com/penberg/agentfs/blob/main/examples/openai-agents/research-assistant/src/agent.ts): agent example · Research-assistant example using AgentFS with OpenAI Agents tooling. · `examples/openai-agents/research-assistant/src/agent.ts`
- [Mastra app](https://github.com/penberg/agentfs/blob/main/examples/mastra/research-assistant/src/mastra/index.ts): agent example · Research-assistant example using AgentFS inside a Mastra workflow stack. · `examples/mastra/research-assistant/src/mastra/index.ts`
- [Cloudflare app](https://github.com/penberg/agentfs/blob/main/examples/cloudflare/src/index.ts): serverless example · Workers-based example showing AgentFS in a serverless deployment context. · `examples/cloudflare/src/index.ts`
- [Firecracker app](https://github.com/penberg/agentfs/blob/main/examples/firecracker/firecracker.sh): VM example · 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.

- [Sandbox](https://github.com/penberg/agentfs/blob/main/cli/src/sandbox/mod.rs): runtime isolation · Platform-specific sandbox execution for running programs against mounted AgentFS state. · `cli/src/sandbox/mod.rs`
- [VFS core](https://github.com/penberg/agentfs/blob/main/sandbox/src/vfs/mod.rs): virtual fs · Sandbox-side virtual filesystem, bind, fd table, mount, and SQLite-backed state handling. · `sandbox/src/vfs/mod.rs`

## Connections

- 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.
