code-execution-sandbox

An MCP server that gives an LLM one tool, execute_code: run a short bash or python program in an isolated, network-disabled Docker container and get back its stdout, stderr, and exit code. It's a standalone Go service — a sibling project to Miranda, not a package inside it — meant to be wired into Miranda (or any other MCP client) as one more tool source.

MCP client (Miranda, Claude, ...) <--Streamable HTTP--> code-execution-sandbox <--docker run--> ephemeral sandbox container

The server itself runs host-native — a single static Go binary, no Docker for the process itself — and talks to the local Docker daemon to spawn a fresh, hardened container per call. See CLAUDE.md for the full security model and why this isn't "just run it in Docker too."

Building

Requires Go 1.25+ (the module pins go 1.25.0; with GOTOOLCHAIN=auto — the default — go build fetches a matching toolchain automatically) and a working Docker install (docker CLI + daemon, docker compose).

go build -o code-execution-sandbox ./cmd/code-execution-sandbox
# or
make build

Cross-compiling for another host (e.g. the deploy target) is just:

GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -o code-execution-sandbox-linux-amd64 ./cmd/code-execution-sandbox

Building the sandbox runtime image

Every execute_code call runs against a prebuilt image (docker/sandbox.Dockerfile), never a base image pulled at request time:

docker compose build sandbox
# or
make docker-build

Running

cp config/config.yaml.dist config/config.yaml   # optional — every field has a default
cp .env.example .env
# fill in SANDBOX_MCP_TOKEN in .env

make docker-build   # build the sandbox runtime image, once
make run            # build + run the server

The server listens on :8788 by default: GET /healthz (unauthenticated; also checks the local Docker daemon is reachable) and POST /mcp (the MCP endpoint, requires Authorization: Bearer <SANDBOX_MCP_TOKEN>).

Testing

make test         # go test ./... -race — unit tests everywhere;
                   # internal/sandbox's and test/integration's
                   # Docker-backed tests skip automatically if the
                   # sandbox image hasn't been built yet
make docker-test   # docker-build + test — the full suite, nothing skipped
make lint          # golangci-lint run ./...
make fmt           # gofmt + goimports
make check         # fmt + lint + test — run this before committing

make lint/make check need golangci-lint and goimports on PATH — make tools installs both.

Deploying

./scripts/deploy.sh

Cross-compiles for linux/amd64, ships the binary plus the Docker build context over SSH, rebuilds the sandbox runtime image on the server, and restarts the systemd --user service that runs it. See .claude/skills/deploy/SKILL.md for the full breakdown.

Configuration

Copy config/config.yaml.dist to config/config.yaml and edit it — every field has a built-in default (see internal/config.Default()), so you only need to override what differs:

http_addr: ":8788"
auth_token_env: "SANDBOX_MCP_TOKEN"
logging:
  level: "info"
sandbox:
  image: "code-execution-sandbox-runtime:latest"
  max_concurrent: 4
  default_timeout_seconds: 10
  max_timeout_seconds: 60
  max_code_bytes: 65536
  max_output_bytes: 1048576
  memory_limit: "1g"
  cpu_limit: "1"
  pids_limit: 128

The auth token itself is never put in config.yaml — auth_token_env names an environment variable to read it from at startup. For local development, copy .env.example to .env and fill it in (loaded via internal/envfile; a variable already set in the real environment always wins). The server refuses to start if that variable is unset or empty.

Debug logging