Why one writable checkout breaks under multiple agents
A single coding agent can often use a conventional checkout. With several concurrent agents, that checkout becomes an implicit communication bus. One agent sees another agent’s incomplete files, commands operate on a moving filesystem, and a cleanup script may remove state that another task still needs. Git branches record commits, but they do not isolate every intermediate command and uncommitted write.
Duplicating the complete repository for every agent adds isolation but moves coordination elsewhere. Base files and dependencies are copied, long-running process state is still ad hoc, and a separate merge path must establish which output is trusted. A scalable multiagent workflow needs workspace lifecycle, execution identity, evidence, and publication to agree on the same task boundary.
Shared history with private workspace sessions
Ephemeral Sandbox keeps project history in LayerStack, an ordered chain of immutable layers. A live workspace session leases one exact chain and projects it through OverlayFS. Reads fall through to the shared lower layers; writes go to the session’s private upper directory. Each agent therefore sees a stable base plus only its own intermediate changes.
Commands execute inside a holder-owned namespace tied to that workspace view. The boundary persists across operations, so an agent can start a process, inspect its output later, and continue working with the same filesystem context. A command session is narrower than a workspace session: it tracks one process and transcript, while filesystem finalization belongs to the workspace.
- One stable leased base per workspace session
- Private copy-on-write mutations per agent
- Persistent mount and process namespace ownership
- Stable command sessions for ongoing processes
- Independent runtime and read-only observation APIs
- Explicit finalization after task review
The multi-agent coordination loop
- Decompose work: assign bounded responsibilities and make ownership clear before agents begin.
- Create sessions: give each active task its own workspace session over the current shared LayerStack.
- Execute independently: route command and file operations by sandbox and workspace identifiers.
- Inspect evidence: review results, activity, resources, changed paths, and provenance.
- Publish deliberately: reconcile the accepted change set with the latest shared head.
- Refresh or retire: new sessions see the new head; failed or completed sessions can be destroyed.
Workspace isolation does not eliminate logical conflicts. Two agents can independently change the same API contract or create incompatible assumptions. It ensures that conflicts are discovered at a controlled boundary rather than emerging as accidental interference during execution.
Atomic publication for an agent swarm
Finalization captures the session’s private delta and compares it with the latest LayerStack head. The system resolves changes path by path under optimistic concurrency control. Even though paths are evaluated individually, the result is one publication unit: one immutable layer is added, or no part of the proposed result is published.
This all-or-reject contract matters for multi-agent coding. A partially accepted refactor can leave the repository in a state that no agent intended. An atomic layer makes the accepted task result attributable, inspectable, and easy for subsequent sessions to consume. The architecture chapter explains capture, per-path resolution, and final manifest publication.
Useful multiagent workflow patterns
Parallel implementation
Assign agents to non-overlapping modules, keep each in a private workspace, and publish verified results in dependency order. Later agents can start fresh sessions on the updated head when they need preceding work.
Implementation plus review
Let one agent implement while another uses observability and exported evidence to review. Separate tool groups allow read-only inspection without granting runtime mutation authority.
Competing approaches
Run multiple approaches from the same base, compare tests and evidence, publish the selected result, and discard the others. Private workspaces keep experimental paths from contaminating one another.
Repair after a failed publication
If current head makes a proposed change stale or conflicting, keep the rejection explicit. Rebase the task conceptually in a new session or make a bounded repair, rather than silently accepting only part of the output.
See the workspace and command session concepts or use the quickstart to exercise the model locally.