Skip to content
Ephemeral Sandbox mascot — a Siamese kitten peeking out of its wooden sandbox
Browse docs

Start

Quickstart

Build the clients, start the gateway, create a sandbox, run a command, and clean up.

On this page+

Before you begin

Use a checkout of ephemeral-sandbox with Docker running, Rust 1.85 or newer, and Cargo available. The Docker backend needs a local base image and a Linux-musl daemon artifact matching the container architecture.

Preflight
docker info
docker pull ubuntu:24.04
rustc --version
cargo --version
Content TODO: the gateway launcher also requires dist/git/linux-arm64.tar and dist/git/linux-amd64.tar. The source repository does not currently document a command that creates these archives. Obtain the project-provided artifacts before continuing; no unverified download URL is listed here.

Build the clients

Add the repository wrappers to PATH. They load the shared gateway token and prefer an existing debug binary. Build the three CLI executables and the MCP server together.

Shell
cd /absolute/path/to/ephemeral-sandbox
export PATH="$PWD/bin:$PATH"
cargo build -p sandbox-cli --all-features -p sandbox-mcp

Start the gateway

Bootstrap the musl cross toolchain once, then start the Docker-backed gateway. The rebuild flag forces a fresh daemon package at the architecture configured by manager.docker.daemon_binary_path in config/prd.yml.

Shell
setup-musl-cross
start-sandbox-docker-gateway --rebuild-binary

The launcher prints the gateway address, token file, PID file, and log path. The default address is 127.0.0.1:7878; the wrappers read the token automatically.

Create a sandbox

Confirm the local image, then create a sandbox whose workspace bind root is the current checkout. The create response contains the sandbox ID used by runtime and observability calls.

Shell
sandbox-manager-cli list_docker_images
sandbox-manager-cli create_sandbox --image ubuntu:24.04 --workspace-bind-root "$PWD"
sandbox-manager-cli list_sandboxes

Copy the returned ID for the remaining commands. The examples below use the help surface’s verified placeholder eos-abc; replace it with your value.

Execute and inspect

Run a command through the runtime client, then inspect the sandbox from the separate observability client. With no workspace-session ID, exec_command creates an automatic session, publishes its changes after the last command reaches a terminal state, and destroys that session.

Shell
sandbox-runtime-cli --sandbox-id eos-abc exec_command pwd
sandbox-runtime-cli --sandbox-id eos-abc file_read --path README.md --limit 20
sandbox-observability-cli snapshot --sandbox-id eos-abc

For interactive commands and stable output offsets, continue with the files and commands guide.

Clean up

Inspect the manager record once more, then stop the daemon, destroy the runtime sandbox, and remove the record.

Shell
sandbox-manager-cli inspect_sandbox --sandbox-id eos-abc
sandbox-manager-cli destroy_sandbox --sandbox-id eos-abc
sandbox-manager-cli list_sandboxes

58 results