Skip to content

What is AWC

Agent Workspace Cache (AWC) is an object-storage-backed, content-addressed workspace system for high-fan-out coding-agent fleets. You prepare one Linux environment and fork thousands of private workspaces from it. Each agent reads the shared bytes once and stores only its own changes.

The problem AWC solves

A conventional coding-agent fleet gives each agent its own clone, volume, or sandbox snapshot. When hundreds of agents touch the same codebase, the fleet repeats the same work over and over:

  • copies identical repository bytes;
  • downloads identical packages;
  • reserves volumes for dormant branches;
  • retains full images for tiny changes.

The logical workload grows with the number of agent hypotheses. The physical data does not. Most agents share almost everything.

AWC makes the storage match the workload. Physical storage becomes unique immutable base content, plus unique branch deltas, plus cache overhead — not workspace count times full workspace size. For reads, the goal is that N agents requesting the same object on one cache domain cause one remote fetch and N local readers.

The core promise

Prepare once, fork many, read common bytes once, and store only unique changes.

Four mechanisms carry this: immutable snapshots, constant-time logical forks, a shared host-local cache that coalesces concurrent reads, and explicit durable checkpoints.

The five primitives

The whole user surface is five operations:

snapshot → fork → mount → checkpoint → diff/export

Each primitive exists to make one resource cheap:

  • snapshot encodes a prepared environment as a Merkle tree in a content-addressed store. You pay the byte cost once, at import.
  • fork creates only metadata. It references an existing snapshot plus an empty private delta. Fork cost must stay independent of snapshot size.
  • mount redeems a ticket into an ordinary Linux directory, with one exclusive writer lease. The agent sees normal paths and uses normal tools.
  • checkpoint quiesces the writer, converts the local delta into immutable objects, and advances the workspace head atomically. Writes before a checkpoint are local, not remotely durable.
  • diff and export compare snapshots by a Merkle-tree walk and ship changed bytes as a patch bundle, tar, or JSON.

Consider what changes if you alter a primitive. If fork copied bytes, fork would scale with workspace size, and you would be back to per-agent clones. If every write(2) were remotely durable, AWC would be a distributed filesystem. That brings distributed locking and coherence. The five-primitive surface is a deliberate cut. It covers the agent loop and nothing more.

Who AWC is for

AWC serves fleets whose workload fits a narrow contract:

  • mostly immutable, reusable base state;
  • a private writable delta much smaller than the base;
  • at most one active writer per workspace;
  • explicit checkpoints as an acceptable durability boundary;
  • a minority of workspaces mounted at once;
  • heavy read overlap across agents on the same project;
  • Linux tools that expect normal filesystem paths.

If you need synchronous remote durability for every write, multi-host shared writes, or database-grade distributed locking, you sit outside the MVP contract.

What AWC is not

AWC is an agent workspace cache, not a general filesystem or a platform layer. The MVP explicitly does not provide:

  • concurrent writers to one workspace;
  • shared mutable POSIX semantics across hosts;
  • distributed file locking;
  • remote durability after every ordinary write;
  • live migration of an active writer;
  • a build system, package registry, or remote execution engine;
  • an agent scheduler or model gateway;
  • Windows or macOS mounts;
  • a custom Linux kernel module.

The word cache is the point. The object store holds durable immutable truth. Host-local state is disposable acceleration. Losing it costs performance, never recoverability.

Adjacent features are deferred, not committed. Content-defined chunking, learned prefetch, package and build-cache views, live rebase, a shared mutable handoff directory, multi-region replication, and semantic diff and merge are future directions. Scope creep is a tracked risk. The team must keep the five-operation surface and demand economic evidence for adjacent work.

The trade, stated honestly

AWC trades local simplicity for cross-host byte reuse. On one host, plain copy-on-write is hard to beat. The distinguishing value of AWC is the cross-host regime. Many hosts share one content-addressed base in the object store. The comparison is against a network copy that a local overlay cannot serve.

The MVP must cut remote workspace I/O per agent task, storage per workspace, or time to a prepared workspace by a clear margin. The decisive cross-host advantage is architecturally intended but not yet measured end to end. It needs a second host. Treat the cross-host economics as an open question, not a proven result.

For the how and the exact facts, read the tutorials, the how-to guides, and the reference. For the deeper why, continue to architecture, economics, and scope discipline.