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

Start

Installation

Prepare the toolchain, build the public clients, package the daemon, and start the gateway.

On this page+

Prerequisites

The workspace targets Rust edition 2021 with a minimum Rust version of 1.85. Local Docker must be reachable. Packaging the in-container daemon needs Zig plus cargo-zigbuild, or a configured cross installation.

Verify
docker info
rustc --version
cargo --version

Run bin/setup-musl-cross once to bootstrap the preferred Zig-based path. The packaging task falls back to cross when available.

Build the public tools

The CLI crate produces three authority-specific executables. sandbox-mcp is one binary, but each server process selects exactly one catalog with --set.

Shell
cargo build -p sandbox-cli --all-features -p sandbox-mcp

The console server and SPA are separate. Use bin/start-sandbox-console-stack when you need the browser interface; it builds the assets and server in dependency order.

Package the daemon

The Docker provider uploads a static Linux-musl sandbox-daemon into each container. The package target must match the artifact named by manager.docker.daemon_binary_path.

Shell
bin/setup-musl-cross
cargo run -p xtask -- package

Use --profile release only for the final fat-LTO artifact. The default package-fast profile is intended for local Docker iteration.

Content TODO: the checked launcher requires both platform-specific Git toolchain archives under dist/git, but no source-owned generation workflow is documented. Installation cannot truthfully claim a clean-checkout start until that workflow is published.

Configure PATH and token

Use the repository wrappers so all clients load the same token and find local debug binaries. The gateway creates ~/.ephemeral-sandbox/gateway.token with private permissions and reuses it.

Shell
export PATH="$PWD/bin:$PATH"
sandbox-gateway-token path

Set SANDBOX_GATEWAY_TOKEN_FILE when a service installation needs a system-managed token location. Do not place the token in YAML or expose it to browser code.

Start and verify

The launcher builds the host gateway and clients, packages a stale or missing daemon, stops only the gateway referenced by its verified PID file, and starts a new background process.

Shell
start-sandbox-docker-gateway --rebuild-binary
sandbox-manager-cli list_sandboxes
sandbox-observability-cli snapshot

If startup fails, use the log path printed by the launcher and follow the gateway troubleshooting checks.

58 results