Ephemeral Sandbox: Coding-Agent Swarm Infrastructure

Raise the concurrency ceiling for coding-agent swarms with isolated workspace
sessions inside one shared sandbox.

Docs ·
Quick start ·
MCP ·
CLI ·
Architecture ·
Tests

Ephemeral Sandbox is open-source coding-agent swarm infrastructure: many
parallel agents collaborate, each through an isolated workspace session inside
one shared sandbox, replacing single-checkout concurrency limits with safe,
reviewable publishing.

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.

Why Ephemeral Sandbox?

• 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.
• Publish with confidence. Inspect activity and change provenance before
  publishing a complete resolved change set.

Quick start

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.

Linux amd64

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.

macOS arm64 (Apple silicon)

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-gateway

More details: macOS setup.

Windows amd64

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.ps1

More details: Windows setup.

Console / Desktop UI

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.

Choose an interface

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

How it works

1. Share a stable base. LayerStack keeps the project history available to
   every workspace session.
2. Work in isolation. Each agent gets its own writable workspace and
   execution boundary.
3. 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

• Documentation
  covers the overview, CLI, MCP, and architecture.
• 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,
  or sandbox-observability-cli help for installed command syntax.

Community

Ask questions and share feedback in the
Ephemeral AI Lab Discord.

How to contribute

Focused fixes, documentation improvements, and tests are welcome. Before
opening a pull request, run:

cargo fmt --check
cargo clippy --all-targets
cargo test

Keep the change focused and describe what it changes, why it is needed, and how
you verified it in the pull request.

License

Ephemeral Sandbox is available under the Apache License 2.0.