Getting started

This tutorial takes you from nothing to a running sandbox stack in about ten minutes. At the end you will have a worker polling Anthropic’s queue for sessions and an MCP tunnel listening locally.

Prerequisites

You need git and one of the following, in order of preference: Docker with the compose plugin, Podman with compose support, or Bun 1.3 or later for a tunnel-only setup. You also need a Claude Managed Agents environment key from the Anthropic Console; the sandbox contract explanation covers what this key is and why it is the only credential the host ever holds.

Install with the launcher

The launcher clones the repository if needed, probes your machine, prints its decision trail, and starts the best mode it finds.

git clone https://github.com/danielbodnar/systemd-claude-sandbox.git
cd systemd-claude-sandbox
bash install.sh

A typical decision trail looks like this:

install.sh: platform: linux
install.sh: already inside a clone: /home/you/systemd-claude-sandbox
install.sh: probes: engine=docker compose=docker compose bun=yes just=yes vscode=no devcontainer-cli=devcontainer
install.sh: decision: compose stack via just (engine: docker)

Tip

On Windows, run the script from Git Bash or WSL. It prefers an installed WSL distro, falls back to VS Code with the devcontainer when Docker is present, and offers an interactive menu when neither exists. Force a mode any time with CLAUDE_SANDBOX_MODE=compose|devcontainer|bare|wsl.

Or bring the stack up manually

1. Copy the environment template and fill in your credentials.

   cp .env.example .env

   Set ANTHROPIC_ENVIRONMENT_KEY and ANTHROPIC_ENVIRONMENT_ID from your Console-created self_hosted environment. Leave ANTHROPIC_API_KEY out; the worker host must never hold it.

2. Build and start the stack.

   just

   just build
   just up

   docker compose

   docker compose build
   docker compose up -d

3. Confirm both services are healthy.

   just ps
   # NAME                        STATUS
   # claude-sandbox-worker-1     Up
   # claude-sandbox-mcp-tunnel-1 Up

4. Watch the worker claim its first session.

   just logs worker

   Create a session against your environment from any machine that holds your API key, and the worker picks it up within a poll interval.

What you now have

• compose.yaml the stack definition
• .env your credentials, never committed
• Directorysandbox/

  • Dockerfile worker and dev images, one lineage
  • spawn.sh optional per-session isolation
• Directorymcp-tunnel/ Streamable HTTP reverse proxy

  • …
• Directoryhost/systemd/ unit for production hosts

  • …

The tunnel listens on 127.0.0.1:8787 and stays loopback-only until you choose a publish transport, which is an open decision awaiting maintainer confirmation.

Next steps

• Deploy to your own host turns this local stack into a supervised service on a server.
• Compose services reference explains every service and volume you just started.