What is an agent sandbox?
An agent sandbox gives an AI agent a bounded place to run commands, read context, change files, and return evidence. For coding agents, isolation is only half of the problem. The system also needs to preserve task state across commands, expose useful control interfaces, and define how completed work enters the shared repository.
Ephemeral Sandbox is an open-source implementation of that coordination layer. It does not put every coding agent into the same mutable checkout. A manager-owned sandbox contains a shared LayerStack and one or more isolated workspace sessions. Each session owns its writable upper layer and execution namespace, while lower project history remains stable and shareable.
The Ephemeral Sandbox model
The core design separates durable filesystem truth from a temporary execution view. LayerStack orders immutable base, published, and squashed layers. A lease pins the lower chain used by a live session. OverlayFS projects that chain with a private upper directory, and the namespace holder keeps the process and mount view available across runtime operations.
When an agent’s work is ready, finalization captures its private changes and compares them with the latest shared head. Conflicts resolve per path, but publication remains all-or-nothing: the resulting immutable layer is added once, or the complete publication is rejected. That distinction keeps partially accepted task output from silently leaking into shared history. See the workspace coordination chapter for the publication contract.
- Shared immutable project history
- Private copy-on-write workspace sessions
- Holder-owned namespace execution
- Command and file operations with stable IDs
- Read-only health and activity evidence
- Conflict-aware atomic publication
A parallel coding-agent workflow
- Create a Docker-backed sandbox from a declared image and workspace.
- Assign an explicit workspace session to each coding agent or task.
- Run commands and file operations against the relevant sandbox ID and session ID.
- Inspect health, events, resources, file activity, and line attribution.
- Finalize accepted work through the publication gate; reject or destroy abandoned work.
This pattern works for a small pair of agents and for a larger agent swarm. Concurrency does not remove the need for task decomposition or review. It changes the failure mode: agents can explore independently without sharing intermediate writes, and the system can make promotion a separate, observable decision.
CLI, MCP, and browser interfaces
Public operations are divided into three groups. Management creates, inspects, exports, and destroys sandboxes. Runtime executes commands and reads or changes files. Observability reports health, events, resource use, and filesystem evidence. The CLI uses separate executables for those groups, while each MCP server process selects one fixed tool set.
sandbox-manager-cli help
sandbox-runtime-cli --sandbox-id ID help
sandbox-observability-cli help
sandbox-mcp --set management
sandbox-mcp --set runtime
sandbox-mcp --set observabilityThe same semantic operation catalog backs the CLI and MCP surfaces. This lets an operator use shell automation while an MCP-compatible agent uses structured tools, without inventing a second lifecycle vocabulary. The documentation lists supported operations and their request shapes.
When this agent sandbox fits
Ephemeral Sandbox fits teams running multiple coding agents against one codebase on local or Docker-backed infrastructure. It is particularly useful when private intermediate state, reviewable execution, line provenance, and deliberate publication matter more than disposable command execution alone.
It is not presented as a hosted multi-tenant platform or a hardened microVM for arbitrary adversarial workloads. Operators remain responsible for host, Docker, network, image, and credential policy. Read the security boundary before using it with code you do not trust.
To evaluate the implementation, inspect the Ephemeral Sandbox GitHub repository, review the architecture, and run the local quickstart.