Docker Build and Configuration#

LangBot ships a single multi-purpose Docker image (rockchin/langbot) that powers three distinct services: the main bot, the plugin runtime, and the Box sandbox service 1. The image is built for linux/amd64 and linux/arm64 and published automatically on GitHub Release via CI 2.

Dockerfile Structure#

The Dockerfile uses three build stages to keep the final image lean:

1. node:22-alpine AS node — builds the web UI (npm install && npx vite build) 3
2. python:3.12.7-slim AS nsjail-build — compiles nsjail v3.6 from source; only the binary and its runtime libs (libprotobuf32, libnl-route-3-200) are carried into the final stage, keeping the compile toolchain (bison, flex, protobuf-dev) out of the final image 4
3. Final python:3.12.7-slim — copies the built web dist and nsjail binary, then installs:
   • Docker CLI (client only) for the optional Box Docker backend 5
   • Node.js LTS so npx-launched MCP servers are available inside the nsjail sandbox chroot 6
   • Python dependencies via uv sync 7
   • A /.dockerenv sentinel file to signal container context 8

The default entrypoint is uv run --no-sync main.py 9.

CI: GitHub Actions Build#

The build-docker-image workflow triggers on release: published. It uses docker buildx for multi-arch builds:

• Stable release: tags rockchin/langbot:<version> and rockchin/langbot:latest 10
• Pre-release: tags version only — latest is not updated 11

docker-compose Services#

The docker-compose.yaml defines three services, all using the same rockchin/langbot:latest image:

langbot_box mounts /var/run/docker.sock to drive the host Docker socket and create sibling sandbox containers 12. The Box root path is configured via LANGBOT_BOX_ROOT (default: ${PWD}/data/box); the host and container paths must be identical because sibling containers are created with matching bind mounts 13.

Key env-override convention for langbot: BOX__<SECTION>__<KEY> maps to box.<section>.<key> in config.yaml and is forwarded to the Box runtime via RPC 14.

Sandbox Backends#

BoxRuntime 15 probes three backends at startup in priority order: Docker → nsjail → E2B. The active backend is selected by box.backend in config.yaml (values: local, docker, nsjail, e2b, host); if unset, the first available local backend is used 16.

• Docker (DockerBackend): wraps the Docker CLI. Creates containers labeled langbot.box=true, enforces --cpus, --memory, --pids-limit, and --read-only rootfs with a tmpfs /tmp. CPU limiting can be disabled via BOX__DOCKER__CPU_LIMIT_ENABLED=false 17.
• nsjail (NsjailBackend, name="nsjail"): uses the nsjail binary embedded in the image — no Docker socket required. Sessions persist state via host-directory bind mounts; uses cgroup v2 resource limits with rlimit fallback.
• E2B (E2BSandboxBackend): cloud (E2B) or self-hosted (CubeSandbox) backend. Requires the e2b Python package and E2B_API_KEY. Since there are no real bind mounts, the runtime syncs host files in/out before and after each execution 18. /workspace is transparently remapped to /home/user/workspace 19.
• host: runs code directly on the host system as the Box Runtime user without any sandbox isolation. This backend is never auto-selected and must be explicitly configured via box.backend: host. It provides no image, filesystem, network, PID, CPU, memory, or storage isolation and should only be used in trusted local development environments. Not recommended for production use.

BoxSpec and Custom Sandbox Images#

BoxSpec is the Pydantic model that controls every sandbox execution. Key fields:

20

The default sandbox image is rockchin/langbot-sandbox:latest. To use a custom sandbox image, set image to any Docker image name in BoxSpec. For E2B, image is interpreted as the E2B template ID unless overridden by the e2b.template config option 21.

BoxProfile provides reusable preset configurations. Built-in profiles: default, offline_readonly, network_basic, network_extended. Fields listed in locked cannot be overridden by tool-call parameters 22.