A sandbox can disappear; its workspace should still come back from an atomic checkpoint—not from a bucket, a hand-rolled schema migration, and hope.
A friend building agent harnesses called persistent, atomically replayable workspace state a requirement, not a feature. Another hit the cost of building that state on SQLite: changing a column type or primary key still means rebuilding the table and its dependencies. NoKV exists because durable bytes are only half the problem; the metadata that gives them identity has to survive and evolve too.
The status quo is a bucket, a database, and hope
Say an agent spends forty minutes producing a report and its supporting files inside a sandbox. Then the sandbox is reaped.
Keeping the machine alive turns disposable compute into storage. Copying the files to an object store is better, but now a database has to remember which object belongs to which path, which version won, what a retry means, and when old data is safe to delete. Unless every one of those rules is rebuilt in the application, the bucket and the database drift and the last writer wins.
NoKV’s position is simple: an agent workspace needs a storage contract of its own.
The workspace outlives the sandbox
In NoKV, an agent publishes files into a Workbench. Once published, a client on the same NoKV deployment can find a file by its root, Workbench, and path—even after the original sandbox is gone.
That address resolves in three steps. NoKV first resolves the Workbench’s never-reused incarnation. The path head then points to the current immutable ArtifactRevision. Its manifest points to immutable object blocks.
The live path can advance to a new generation without rewriting the revision that came before it. If one exact run must remain addressable long term, seal it as a commit. A snapshot is different: it keeps a leased point in time for bounded recovery, not a permanent archive.
Writes never guess
Whole-file publication has no blind upsert.
A create succeeds only when the path is absent. A replacement succeeds only when the path exists and its generation still matches the version the caller observed. If another writer moves the path first, the stale write fails instead of silently replacing the winner.
Append validates the same kind of generation fence before advancing the live path. At the lower path-native SDK and protocol layer, rename and remove are generation-fenced too. Workbench commit has its own explicit concurrency conditions. The surface changes; the rule does not: a mutation must prove which state it is changing.
Object blocks follow create-if-absent. The same key with the same bytes is a retry. The same key with different bytes is a collision and cannot overwrite what is already there. Before an object provider can hold real data, NoKV probes those behaviours rather than trusting a configuration flag.
Metadata decides what stays alive
NoKV never lists a bucket to infer whether a path exists or an object is still reachable. Metadata is the authority.
Live paths, revisions, commits, snapshots, operation holds, and manifests all take part in the lifecycle. Snapshots and in-progress scans protect older metadata with read-version history holds. A manifest remains the deletion plan for the physical blocks behind a revision.
Reference counts matter, but they are only one GC condition. NoKV can delete an object only after every authoritative reference and hold says it is unreachable.
Retries are designed, not hoped for
Agent pipelines retry. Schedulers resubmit. Sometimes the server commits a write and the response disappears on the way back.
An RPC retry with the same request identity returns the stored result. Durable operations do the same when their operation identity and inputs match; changed inputs are rejected.
In one anonymous materials-science pilot, real task documents were driven through successful retries, partial failures, and lost responses. Duplicate submissions produced an explicit retry or conflict result—never a silent overwrite.
This is not universal exactly-once. A fresh append request after an ambiguous response is a new operation and may append the same bytes again. If a pipeline cannot tolerate that, it should publish a complete file against a pinned generation.
Commit, snapshot, and restore solve different problems
A commit seals every file visible at one read version into an immutable workspace tree. It is the durable reference for an exact run and remains valid after live paths move on.
A snapshot is a leased MVCC point in time. It exists for bounded recovery and expires unless renewed.
Restore starts from a commit or an active snapshot and creates a new Workbench. Within the same root and shard, it reuses the existing object bytes and rebuilds only metadata and references. The source stays unchanged, and the restored copy gets a fresh incarnation.
Strong enough to coordinate on
These semantics are useful beyond file storage because they let another system coordinate without asking NoKV to become its scheduler.
LoopX, an independent open-source agent orchestration project, is integrating NoKV as an optional storage provider behind its own coordination authority through a public staged RFC. The RFC and its first two stages are merged; recovery is still under review.
The proposed recovery design is built around the same primitives described here: create-only artifacts, fenced head updates, typed conflicts, and a store identity bound to the Workbench incarnation. If an executor loses ownership, it cannot publish again. If a restored Workbench has identical files but a new incarnation, it cannot quietly impersonate the original.
That is the useful boundary: LoopX remains the coordination authority; NoKV makes the files and receipts durable enough for that authority to reason about.
One owner, many requests
Each logical shard has one active owner, and authoritative metadata mutations serialize at that owner’s commit gate.
That does not mean one request at a time. Static validation, canonical hashing, dedupe-key construction, and immutable-object I/O can overlap. The gate serializes the authoritative metadata decision, not the upload.
In the default local-only deployment, the complete Holt metadata directory is
the recovery authority. Protect it and back it up as one unit. Reopening that
same directory after a crash is qualified; restoring a copied directory on
another machine, cross-host failover, and production metadata HA are not.
Mounts solve a different problem
Archil and Amulet approach disposable workspaces through a mounted filesystem. That is a real advantage when unmodified tools need ordinary POSIX paths.
But the mount is only one part of each product’s contract. Archil documents a strongly consistent disk view and eventual synchronization with an attached data source; same-path writes from both sides can be unsafe. Its branches and checkpoints apply to disks that are not synchronized with an external data source.
Amulet shows that a mount can coexist with stronger publication semantics. It adds isolated branches, immutable commits, and compare-and-swap publication at the workspace head, so conflicts are checked when work is published.
NoKV makes a different trade. It does not expose a POSIX mount. Tools integrate through explicit Workbench operations, and path generations, immutable revisions, retention, and GC share one metadata authority. The contract and its Apache-2.0 implementation are open to inspect.
Choose a mount when compatibility with existing filesystem tools is the main problem. Choose an explicit workspace contract when the files are the durable record of what agents did.
Where the boundary is today
NoKV does not provide cross-shard transactions. Production metadata HA across machines is not qualified. Tenant identity and RBAC are not enforced at the service boundary; NoKV currently trusts its callers.
NoKV may grow into these areas, but none comes with a date or a guarantee today.
Try it against your own failure model
The implementation and its failure tests are public. Pick the failure you actually care about—a reaped sandbox, a scheduler submitting twice, or two agents racing on one path—and run it.
The useful question is not whether the storage looks familiar. It is what survives when the agent does not.