Agent filesystem
The experimental Coven Agent File System foundation, its present boundary, and its public roadmap.
4 min read
Coven is exploring an Agent File System (AFS): a local SQLite-backed filesystem foundation for agent work that stores file state without making the project directory itself the working store. The future design adds session-linked change history and provenance; that integration is not implemented today.
This is experimental engineering infrastructure, not a supported user-facing
workflow yet. There is no coven afs command, AFS daemon API, daemon-managed
mount point, or sandboxed execution mode to configure today.
What is shipped
The coven-afs Rust crate is merged in the public Coven repository. It
implements an AgentFS SPEC v0.4-compatible
SQLite storage layer with:
- POSIX-like files, directories, hard links, and symbolic links;
- chunked file data and filesystem consistency checks;
- a writable copy-on-write delta over a read-only base;
- whiteouts for deletions and full-file copy-up for modified base files;
- a JSON key-value store and insert-only tool-call audit records.
An opt-in mount feature also provides an experimental NFSv3 export for
engineering validation. Its loopback-only example uses the platform NFS client
on macOS and enables SQLite write-ahead logging (WAL) for the session database.
This is crate-level experimental support, not a CLI or daemon feature.
The storage engine is tested as a crate. It is not yet connected to the Coven daemon, its session lifecycle, or the public local API. It does not replace the project-root guard, existing worktree workflow, or the safety guidance in Security posture.
Experimental mount result
The macOS NFSv3 spike is protocol-correct and mounts without a kernel extension or elevated privileges. In its measured write workloads, WAL brought the storage engine to 0.81–1.29x the host filesystem's elapsed time (lower is better); the package-tree write shape was faster than the host baseline.
It is not ready for agent workflows. On 2026-08-09, a human-operated,
consent-enabled macOS Terminal confirmed the loopback NFS path by mounting the
export, creating a directory, writing a file, and reading back written. That
pass validates the experimental path for that consent-enabled client only; an
automated agent or other client process may still need explicit macOS
network-volume or privacy consent before opening files. Linux/FUSE has not been
evaluated, the NFS export serializes requests through one SQLite connection,
and loopback NFS access control is unresolved.
What it is for
The intended direction is a private delta per agent session over an immutable project snapshot. That would make a session's changes inspectable and discardable without mutating the base snapshot. A future explicit materialization step would apply reviewed changes to an ordinary Git branch, preserving Coven's existing PR workflow.
The storage implementation follows the upstream specification. The future design reserves separate additive tables for Coven-specific provenance, but no such tables are implemented yet. This keeps the filesystem interoperable at the storage layer without treating any upstream tool or format as a runtime dependency.
Important boundaries
Do not rely on AFS for security isolation today:
- No supported mount workflow is shipped. The experimental NFS export is feature-gated, is not started by Coven, and has no CLI or daemon interface.
- No sandbox is shipped. A mount alone would not prevent a process from writing to an absolute path outside that mount.
- No daemon network listener is added. Coven's daemon remains same-user local IPC. The experimental NFS example starts a loopback listener only when an engineer explicitly compiles and runs it.
- No session API is shipped. Session creation, diff, timeline, commit, and discard operations are design work, not public routes or commands.
Use the current project-root guidance and explicit Git/worktree review flow for production work.
Roadmap
The roadmap is capability-based rather than date-based. Each workstream has explicit safety and operational gates before it becomes a supported feature.
| Phase | Status | Scope and gate |
|---|---|---|
| Storage foundation | Shipped experimental | coven-afs provides the SPEC-compatible schema, filesystem operations, and copy-on-write overlay. |
| macOS NFS and performance spike | Shipped experimental | A feature-gated NFSv3 export and benchmark show a conditional storage-engine GO with WAL. Human Terminal validation passed; the result requires a client-/harness-specific macOS privacy or network-volume access assessment, while concurrent-client evaluation and Linux/FUSE remain open. |
| Mount safety decision | Planned after spike | Resolve loopback access control, default-off behavior, copy-up limits, base-ingest filters, platform-specific recovery, and the remaining per-process privacy consent requirement before enabling any mount by default. |
| Daemon session integration | Planned | Add an additive local API for creating, inspecting, diffing, committing, and discarding AFS sessions. SDK-only operation remains viable if no mount backend is available. |
| Provenance and review | Planned | Connect file operations to Coven sessions and tool calls, then expose explicit diff, timeline, and materialization views to local clients. |
| Broader platform support | Later | Evaluate a Windows-native path separately; no Windows mount backend is promised. |
The NFS spike is shipped experimental work, not a release commitment for a mount workflow. Its remaining safety gates control mount availability and defaults; they do not block future SDK or daemon integration. The daemon API, provenance views, and Git materialization are technical designs only until they are implemented, tested, and documented as supported features.
Follow progress
- Coven architecture explains the current daemon authority boundary.
- Security posture describes the current local-access model.
- The Coven repository contains the experimental storage crate, mount-spike results, and engineering design.
Last updated on