Open-source agent sandbox infrastructure for parallel coding agents.
Website · Docs · Quick start · MCP · CLI · Architecture · Tests
Ephemeral Sandbox is open-source agent infrastructure for running parallel coding agents against the same codebase. Each agent works through an isolated workspace session inside one shared sandbox, then publishes a reviewable change set.
As agent sandbox infrastructure for a multi-agent system, Ephemeral Sandbox gives every coding agent an isolated workspace session without duplicating the underlying sandbox or forcing agents into one mutable checkout.
This repository contains the headless Rust core: gateway, manager, daemon, runtime, observability, CLI, and MCP components. The browser UI and its backend live in the separate Ephemeral Sandbox Console repository.
- Work in parallel. Run multiple coding agents at the same time.
- Stay isolated. Give every agent a private writable workspace session over one stable project base.
- Scale an agent sandbox. Run an agent swarm in one shared sandbox while each coding agent keeps its own workspace session.
- Publish with confidence. Inspect activity and change provenance before publishing a complete resolved change set.
Ephemeral Sandbox provides workspace isolation for cooperating coding agents. It is not a hardened microVM boundary for mutually untrusted tenants. Read the agent sandbox security model before choosing a deployment boundary.
Choose your host OS. Docker must already be installed and reachable. For full commands, CLI verification, and troubleshooting, use the detailed setup guides: Linux, macOS, or Windows.
curl -LO https://github.com/Ephemeral-AI-Lab/ephemeral-sandbox/releases/latest/download/ephemeral-sandbox-linux-amd64.tar.gz
tar -xzf ephemeral-sandbox-linux-amd64.tar.gz
cd ephemeral-sandbox-linux-amd64
nohup bin/start-sandbox-linux-docker-gateway >/tmp/eos-gateway.log 2>&1 &More details: Linux setup.
curl -LO https://github.com/Ephemeral-AI-Lab/ephemeral-sandbox/releases/latest/download/ephemeral-sandbox-macos-arm64.tar.gz
tar -xzf ephemeral-sandbox-macos-arm64.tar.gz
cd ephemeral-sandbox-macos-arm64
bin/start-sandbox-macos-docker-gatewayMore details: macOS setup.
curl.exe -LO https://github.com/Ephemeral-AI-Lab/ephemeral-sandbox/releases/latest/download/ephemeral-sandbox-windows-amd64.zip
tar.exe -xf ephemeral-sandbox-windows-amd64.zip
cd ephemeral-sandbox-windows-amd64
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\bin\start-sandbox-windows-docker-gateway.ps1More details: Windows setup.
The UI lives in the separate Ephemeral Sandbox Console repository. Start the gateway above, then point the console at:
- socket:
127.0.0.1:7878 - Linux/macOS token:
$HOME/.ephemeral-sandbox/gateway.token - Windows token:
$HOME\.ephemeral-sandbox\gateway.token
The console serves the browser UI at http://127.0.0.1:7880.
| Interface | Best for | Start with |
|---|---|---|
| CLI | Operators, scripts, and local development | sandbox-manager-cli help |
| MCP | Coding agents and MCP-compatible clients | bin/setup-codex-mcp |
The CLI and MCP interfaces use three focused tool groups:
- Management creates, inspects, exports, and destroys sandboxes.
- Runtime runs commands and reads or changes files inside a sandbox.
- Observability inspects health, events, resources, and filesystem layers.
Each MCP server exposes one tool group:
sandbox-mcp --set management
sandbox-mcp --set runtime
sandbox-mcp --set observability- Share a stable base. LayerStack keeps the project history available to every workspace session.
- Work in isolation. Each agent gets its own writable workspace and execution boundary.
- Publish safely. Ephemeral Sandbox checks concurrent changes before publishing the complete resolved change set, or publishes nothing.
For the deeper design, see the architecture overview.
- Documentation covers the overview, CLI, MCP, and architecture.
- Learn what an ephemeral sandbox is, how an agent sandbox works, and how the pieces fit together as agent infrastructure.
- See the multi-agent coding workspace model and the narrowly scoped parallel-agent benchmark.
- External tests and benchmarks live in their own repository.
- Repository-local notes cover configuration, Linux setup, macOS setup, Windows setup, daemon HTTP, and maintainer boundaries.
- Run
sandbox-manager-cli help,sandbox-runtime-cli --sandbox-id ID help, orsandbox-observability-cli helpfor installed command syntax.
Ask questions and share feedback in the Ephemeral AI Lab Discord.
Focused fixes, documentation improvements, and tests are welcome. Before opening a pull request, run:
cargo fmt --check
cargo clippy --all-targets
cargo testKeep the change focused and describe what it changes, why it is needed, and how you verified it in the pull request.
Ephemeral Sandbox is available under the MIT License.