Reference
Sandbox
Setup recipes provision the developer toolchain and user identity layered into every project sandbox image.
Image Recipes
overplane sandbox build assembles the selected setup recipe, optional
feature recipes, extra packages, and agent installs into a deterministic image
build. Everything below ships embedded inside the
overplane binary as a typed, schema-validated registry.
Image Recipes
| Recipe | Package family | Default base image |
|---|---|---|
debian | debian | debian:bookworm-slim |
alpine | alpine | alpine:3 |
Setup recipe: debian
Provisions a Debian (bookworm or compatible) base image: UTC timezone, full apt upgrade, then a broad developer toolchain installed from official upstream sources where it matters - Go from go.dev tarballs, Rust via rustup (stable, minimal profile), Node.js from NodeSource, uv via pip - plus build-essential, pkg-config, libssl-dev, git, ripgrep, rsync, jq, htop, procps, tini, z3, python3, and sudo.
Browser testing (Playwright and Chromium) is optional via the playwright feature recipe in sandbox.feature_recipes (enabled by default in new projects).
Project-specific extra_packages.debian entries install in their own layer so they never invalidate the cached toolchain layer. This is the default recipe.
Required
package_family
string default "debian"Package manager family; extra_packages entries under this key are installed into the image.
default_base_image
string default "debian:bookworm-slim"Base image used when agent.container.base_image is not set.
fragments
array<string>Provisioning script fragments, applied in order as separate image layers: debian-base-setup, debian-install-deps, debian-extra-packages.
user_fragment
string default "linux-setup-user"Fragment that creates the container user mirroring the host identity (uid, gid, username, home) with passwordless sudo.
Setup recipe: alpine
Provisions an Alpine Linux base image with best-effort toolchain parity to the debian recipe using apk: build-base, git, ripgrep, rsync, jq, htop, procps, tini, z3, python3 with uv, bash, and sudo.
Browser testing is optional via the playwright feature recipe (distro chromium on alpine; Playwright does not publish musl browsers).
Known gaps versus debian: Go, Node.js, and Rust install from the Alpine package repositories (musl builds), so their versions track the Alpine release rather than the upstream version arguments honored by the debian recipe. All four agent CLIs ship musl-compatible builds and work unchanged.
Required
package_family
string default "alpine"Package manager family; extra_packages entries under this key are installed into the image.
default_base_image
string default "alpine:3"Base image used when agent.container.base_image is not set.
fragments
array<string>Provisioning script fragments, applied in order as separate image layers: alpine-base-setup, alpine-install-deps, alpine-extra-packages.
user_fragment
string default "linux-setup-user"Fragment that creates the container user mirroring the host identity (uid, gid, username, home) with passwordless sudo.