Skip to content

AWC — Agent Workspace Cache

AWC is an object-storage-backed, content-addressed workspace system for Linux coding-agent fleets. A platform prepares one development environment, forks thousands of private workspaces from it without copying data, and mounts each one as a normal directory. Agents keep using ordinary tools. Shared content is cached once per host. Writes stay private until they are checkpointed.

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

The first release exposes five user-level primitives:

snapshot → fork → mount → checkpoint → diff/export

AWC is deliberately not a general distributed filesystem, a sandbox, an agent orchestrator, or a shared multi-writer filesystem (scope discipline).

Tutorial

Your first workspace

Import a snapshot, fork, mount, edit, checkpoint, and export. End to end, in one sitting.

 Tutorial

See the economics

Fan out 100 workspaces from one base and watch the backend reads collapse to one.

 How-to

Solve a goal

Import, fork, mount, checkpoint, deploy, operate, and develop. Step-by-step answers.

 Reference

Look it up

CLI flags, configuration, environment variables, metrics, APIs, and on-disk formats.

 Explanation

Understand the design

Why content addressing, caching, singleflight, leases, and explicit durability.

 Explanation

What AWC is not

The guardrails that keep the product narrow and the wedge sharp.

Why AWC

Coding-agent fleets clone the same repositories, install the same dependencies, and read many of the same files, hundreds of times over. The number of agent hypotheses scales linearly; the underlying data does not. AWC makes the physical system match that workload:

  • One shared base for many logical workspaces.
  • One host-level fetch for correlated reads across many agents (singleflight).
  • Constant-time forks — forking creates metadata, not a copy (no hidden copy on fork).
  • Explicit durability — only checkpoints survive host loss, not every write (the durability model).
  • Pricing on unique bytes and real materialization, not logical volume count (economics).

Who it is for

The first user is the infrastructure team behind a coding-agent, code-review, security-analysis, migration, evaluation, or internal developer-AI platform. The best first workloads have 50 to 500 concurrent agents, 20 or more agents per prepared base, environments of 5 to 50 GB, correlated reads, private deltas below roughly 5 percent of the base, and task lifetimes of minutes to hours.

AWC is not intended for small fleets, large per-agent datasets, continuously active workspaces, shared multi-writer POSIX workloads, or applications that need remote durability on every write.

Get started

The fastest way to see AWC work on a laptop is the local-dev smoke, which stands up PostgreSQL and an S3-compatible store in containers and runs the binaries on the host. Walk through it in Your first workspace, or read the architecture overview first.