The stack reads configuration from a .env file next to docker-compose.yml.
The installer generates one with strong random secrets on first run, so a default
install needs no manual configuration. Override anything below by editing
.env (or passing the variable to the installer) and re-running
docker compose up -d.
Minimal to get started
On a default install these are auto-generated. Set them yourself only if you want
specific values:
| Variable | Default | Description |
|---|
QBOX_SITE_ADDRESS | :443 | Public address Caddy serves. A real domain enables automatic Let’s Encrypt; an IP or :443 uses a self-signed cert. |
QBOX_DATA_DIR | /var/lib/qbox | Host directory for all persistent data. Put it on an xfs/btrfs (reflink) disk. |
Secrets
Auto-generated by the installer; rotate by editing .env.
| Variable | Default | Description |
|---|
POSTGRES_PASSWORD | (random) | Postgres password. |
QBOX_SESSION_SECRET | (random) | Signs dashboard session cookies. openssl rand -hex 32. |
QBOX_S3_ACCESS_KEY | qboxadmin | Object-storage access key. |
QBOX_S3_SECRET_KEY | (random) | Object-storage secret key. |
Public access & TLS
| Variable | Default | Description |
|---|
QBOX_SITE_ADDRESS | :443 | See above. Domain → Let’s Encrypt (the domain must already point at this host’s public IP, with 80+443 open, or the cert won’t issue); IP/:443 → self-signed. |
QBOX_PUBLIC_URL | derived from QBOX_SITE_ADDRESS | Origin used for cookies + CORS, e.g. https://qbox.acme.com. |
QBOX_TLS_DIR | ./tls | Directory mounted into Caddy for a bring-your-own certificate. |
QBOX_TLS_CERT | (unset) | Path (inside the proxy) to your TLS certificate. Drop tls.crt in QBOX_TLS_DIR. |
QBOX_TLS_KEY | (unset) | Path to your TLS private key (tls.key in QBOX_TLS_DIR). |
QBOX_COOKIE_SECURE | true | Session cookies are HTTPS-only. Keep true behind Caddy. |
Sandboxes
| Variable | Default | Description |
|---|
QBOX_DEFAULT_SANDBOX_TIMEOUT_SECONDS | 300 | Auto-kill window (from spawn) when a spawn request omits timeoutSeconds. e2b parity; clients extend it via setTimeout, and an explicit 0 on spawn disables it. |
QBOX_HOST_RETENTION | 24h | Delete a host row silent (no heartbeat) for this long that holds no active sandboxes; it re-registers automatically if it returns. |
Images
| Variable | Default | Description |
|---|
QBOX_IMAGE_REPO | ghcr.io/utibeabasi6 | Registry/namespace for the qbox images. |
QBOX_VERSION | latest | Image tag to run. Pin a semver (e.g. 1.4.2, or a moving 1.4 / 1) for reproducible deploys; also baked into the host agent as its reported version. |
Storage & assets
| Variable | Default | Description |
|---|
ASSETS_DIR | ./assets | Host directory holding firecracker, jailer, vmlinux, qboxd, and dropbear. |
QBOX_S3_BUCKET | qbox-artifacts | Bucket for rootfs/snapshot/kernel artifacts. |
QBOX_KERNEL_SHA256 | (unset) | Optional pin: warn at startup if the staged vmlinux hash differs. The builder auto-detects and uploads the staged kernel, so you normally leave this empty. |
Database
| Variable | Default | Description |
|---|
POSTGRES_USER | qbox | Postgres user. |
POSTGRES_DB | qbox | Postgres database name. |
Host agent
| Variable | Default | Description |
|---|
QBOX_HA_LABEL | host-1 | Human label for this host in the dashboard. |
QBOX_HOST_GRPC_INSECURE | false | Data-plane (control plane ↔ host agent) runs without mTLS. In production this also requires QBOX_HOST_GRPC_INSECURE_ACK=true — otherwise the control plane and host agent refuse to start. The single-host installer sets both; keep 9100 and the SSH-proxy range (40000–49999) firewalled off the internet and the sandbox subnet. For multi-host, leave both false and provide mTLS certs. |
QBOX_HOST_GRPC_INSECURE_ACK | false | Explicit acknowledgment that lets insecure mode run in production on a single trusted host. Prevents accidentally exposing an unauthenticated data plane when scaling out. |
Sandbox resource caps
Per-sandbox cgroup limits on the host-side Firecracker process. Firecracker’s
guest sizing does not bound the host process, so these stop one untrusted
sandbox from starving the host.
| Variable | Default | Description |
|---|
QBOX_SANDBOX_CGROUP_LIMITS | true | Apply per-VM memory.max / cpu.max / pids.max via the jailer. Needs cgroup-v2 controllers delegated to the host agent — the compose runs it with cgroup: host for this. Set false if you run the agent without delegation (otherwise the jailer can’t start firecracker). |
QBOX_SANDBOX_MEM_HEADROOM_MB | 256 | Extra memory above the guest RAM allowed for Firecracker’s own overhead. |
QBOX_SANDBOX_PIDS_MAX | 2048 | PID backstop for the Firecracker process group. |
QBOX_SANDBOX_NET_ISOLATION | true | Each sandbox reaches only the internet — guest↔guest and guest→host traffic is dropped. On by default; set false only as an escape hatch. |
Browser sessions (TURN relay)
The WebRTC live view for browser sessions relays media
through the bundled coturn TURN server. CDP automation works without it — only
the live view needs it. The installer sets QBOX_TURN_HOST and a generated
password automatically; for a manual deploy set them yourself and open the UDP
ports below.
| Variable | Default | Description |
|---|
QBOX_TURN_HOST | (unset) | Public host or IP of the TURN relay — the same address the dashboard uses. The control plane derives the ICE config from it. Set this, or the live view won’t connect. |
QBOX_TURN_PASSWORD | change-this-turn-password | Shared TURN credential — used by both coturn and the injected ICE config, so they must match. Set a real secret. |
QBOX_TURN_USER | qbox | TURN username. |
QBOX_TURN_MIN_PORT / QBOX_TURN_MAX_PORT | 49160 / 49200 | UDP media relay range. Open it on the host and any cloud firewall, along with UDP 3478 (the TURN listener). |
QBOX_BROWSER_ICESERVERS | (derived) | Optional raw ICE-servers JSON to override the derived config (e.g. an external TURN provider). |
The host agent automatically punches a scoped hole in QBOX_SANDBOX_NET_ISOLATION
so sandboxes can reach only coturn’s ports — nothing else guest→host changes.
Builder
| Variable | Default | Description |
|---|
QBOX_BUILDER_CONCURRENCY | 2 | How many template builds run in parallel. |
QBOX_BUILDER_ROOTFS_FREE_MB | 512 | Writable free space added to each template’s rootfs above its image content, so sandboxes can write files. Sized at build time (a sandbox’s disk can’t grow at spawn). 0 = no headroom. |
QBOX_BUILDER_SNAPSHOT_BOOT_TIMEOUT | 3m | How long the builder waits for the guest’s qboxd READY handshake when snapshotting a template. Raise it if cold builds time out (qboxd_not_ready) on a slow disk; a failed attempt is retried automatically. |
Installer asset integrity
The installer verifies each downloaded guest asset against a checksum.
| Variable | Default | Description |
|---|
QBOX_ASSET_BASE_URL | https://assets.qbox.sh/latest | Where vmlinux/qboxd/dropbear (and their .sha256 sidecars) are fetched from — a CDN in front of the qbox asset store. Override to pin a version (…/v1.2.3) or use your own mirror. |
QBOX_ASSET_VERIFY | true | Verify each asset against its sibling <name>.sha256. Disable only on a trusted dev box. |
QBOX_FIRECRACKER_SHA256 | (unset) | Pin the Firecracker release tarball’s SHA-256. Unset → downloaded over HTTPS but not checksum-verified (a warning prints). |
Tips
- After editing
.env, apply with docker compose up -d (recreates only what changed).
- Swap the guest kernel by replacing
assets/vmlinux and restarting the builder:
docker compose up -d --force-recreate builder. Rebuild templates to adopt it
(a Firecracker snapshot can’t resume on a different kernel).