Ephemeral Sandbox mascot — a Siamese kitten peeking out of its wooden sandbox

Open-source agent sandbox infrastructure

Ephemeral sandbox for parallel coding agents.

One sandbox. Many isolated agent sessions. One shared LayerStack.

Run an agent swarm inside one sandbox without forcing every coding agent into the same writable workspace. Each gets a private COW workspace session and holder-owned namespace over the shared LayerStack, then publishes through an optimistic concurrency control gate that commits every resolved path—or none.

See how it worksRead the quickstart
  • One sandbox · many sessions
  • COW + namespace isolation
  • OCC + auditability
Ephemeral Sandbox mascot — a Siamese kitten peeking out of its wooden sandbox
Many agents · one sandboxisolated workspace sessions · concurrent execution

Product definition

What is Ephemeral Sandbox?

Ephemeral Sandbox is open-source agent-sandbox infrastructure for teams running multiple coding agents safely against one codebase. Instead of giving every agent access to the same writable checkout, it creates a private copy-on-write workspace session for each agent over a shared, immutable LayerStack. Commands run inside a holder-owned Linux namespace, so the session’s filesystem and process boundary persist across operations. When work is ready, Ephemeral Sandbox compares the session with the latest shared head, resolves changes path by path, and publishes one atomic layer—or publishes nothing if the change set cannot be accepted. Operators can inspect commands, file activity, resource use, and line provenance through dedicated CLI, MCP, and observability interfaces. The system is designed for local and Docker-backed multi-agent workflows that need parallel execution without sacrificing isolation, reviewability, or deliberate promotion of completed work.

Learn the system

From ephemeral sandbox to multi-agent infrastructure

Start with the category definition, then follow the product, architecture, or workflow path that matches what you are building.

Definition

What is an ephemeral sandbox?

Understand the temporary environment lifecycle, isolation boundary, and finalization choices.

ExploreProduct category

Agent sandbox

Give parallel coding agents private workspace sessions over one stable project base.

ExploreArchitecture

Agent infrastructure

Connect lifecycle, runtime control, evidence, and publication in one control plane.

ExploreWorkflow

Multi-agent coding workspaces

Coordinate an agent swarm without exposing incomplete writes between tasks.

Explore
Run wide

Parallel agents inside one sandbox

Independent workspace sessions keep agent trajectories from trampling one another.

Share the base

One LayerStack, private COW deltas

Sessions share immutable lower paths while each owns its writable upper layer.

Know the result

OCC merge, attributable output

Recheck against head, publish atomically, and map resulting lines back to their owner.

The multi-agent runtime loop

One sandbox. Many isolated sessions. One OCC publish path.

Agents share the sandbox daemon and LayerStack lower paths, but each executes in a holder-owned namespace with its own writable overlay. Coordination happens at publication.

3 agents · 1 sandboxrunning concurrently
Aagent-a
Bagent-b
Cagent-c
One sandbox · one LayerStack
session A
$ cargo fix
running...
upperdir ΔA · ns-A
session B
$ cargo test
running...
upperdir ΔB · ns-B
session C
$ pnpm lint
running...
upperdir ΔC · ns-C
SHARED LAYERSTACK LEASE · HEAD L000023
OBSERVABILITY RAIL
OCC publication gatebase · current head · session delta
L000024 · owner mapnew immutable layer
Agents share one sandbox and LayerStack—not writable state. Each session publishes through OCC.
Start from one truth

Lease the shared LayerStack head

Every workspace session pins the same immutable lower history without cloning the full workspace.

Execute independently

Give each agent an isolated session

Each holder owns its namespace boundary, upperdir, workdir, lease, and private COW delta.

Publish deliberately

Reconcile with OCC

Recheck paths against current head, merge eligible text, and publish every resolved path or none.

Auditability by design

Inspect the run. Attribute the result.

Observability is part of the runtime substrate, not an afterthought. Query live state while agents work, then connect published output to the session or operation that produced it.

Structured runtime evidence

Snapshots, span waterfalls, domain events, resource series, and LayerStack state.

Published-line provenance

Resolve ownership to a workspace session, operation, original base, or unknown.

Durable outside compaction

Ownership metadata remains queryable even as immutable LayerStack history is squashed.

audit trail · eos-abc

# inspect the latest execution trace

$ sandbox-observability-cli trace --sandbox-id eos-abc --trace-id last

trace 8bd1 · exec_command · 1.84s

├─ workspace admission 18ms

├─ namespace launch 41ms

└─ command runtime 1.78s

# read newest-first domain events

$ sandbox-observability-cli events --sandbox-id eos-abc --last-n 3

agent-a command.started trace=8bd1

agent-b command.yielded awaiting stdin

agent-c layer.published L000024

# attribute published lines

$ sandbox-runtime-cli --sandbox-id eos-abc file_blame --path src/auth.ts

1–8    original

9       workspace_session:ws-17

10–12  original

13–14  operation:req-91

Optimistic concurrency control

Recheck head. Resolve paths. Publish atomically.

Session results never overwrite the shared LayerStack as they finish. Publication compares the leased base, current head, and captured delta, then commits one immutable layer—or none.

Explore the interfaces
session A · ΔAvalidate(session)
session B · ΔBauth_test()
session C · ΔClog(session.id)
OCC publication gate · atomicrecheck head · resolve · commit · attribute
Clean merge → new immutable layer
Conflict → no partial publication

Explicit control surfaces

Management, runtime, and observability—through one authenticated gateway.

Use the surface that matches the authority you need. CLI, MCP, and the web console share the same operation semantics without pretending they are one combined command.

Management

Create and manage sandboxes

Discover images and workspaces, create runtimes, inspect lifecycle state, compact, export, and destroy.

sandbox-manager-cli list_sandboxes
Runtime

Execute commands and work with files

Run commands, stream stdin and transcripts, and read, write, edit, or attribute published files.

sandbox-runtime-cli --sandbox-id ID exec_command pwd
Observability

Inspect every active runtime

Query snapshots, traces, events, cgroup resource series, and live LayerStack state.

sandbox-observability-cli snapshot --sandbox-id ID