#sandboxd reference

sandboxd serves the Sandbox API on one machine, one per machine. Every client — the CLI, Studio, the SDKs, a gateway in front of many machines — reaches sandboxes only through it.

This page is the reference: its flags, the policy file, node mode and metrics. Setting a machine up is self-hosting.md on Linux and local-macos.md on a Mac; the API it serves is api/v1.md.

sudo sandboxd --backend firecracker --kernel /var/lib/sandboxd/vmlinux \
  --firecracker /usr/local/bin/firecracker --jailer /usr/local/bin/jailer \
  --policy /etc/sandboxd/policy.yaml \
  --listen 0.0.0.0:7443 --token-file /etc/sandboxd/token \
  --tls-cert /etc/sandboxd/tls/cert.pem --tls-key /etc/sandboxd/tls/key.pem \
  --allowed-host sandbox.example.internal

#Flags

#Serving

#The backend

#As a node behind a gateway

What a node is told and how a gateway reaches it is in fleet.md and self-hosting.md.

#The policy file

--policy /etc/sandboxd/policy.yaml is what requests may ask for. A request may tighten any of it and never loosen it. Every key is optional — what is absent keeps the built-in value — and an unknown key is an error, so a misspelt celing: none cannot leave the server more open than its operator thinks. packaging/systemd/policy.example.yaml is a starting point for a machine shared by a team.

default_image: ghcr.io/you/sandbox-base:1
images: [ghcr.io/you/sandbox-base:1]       # only these may be requested
defaults: {cpus: 2, memory_mb: 2048, disk_mb: 20480, idle_timeout_secs: 3600}
limits:   {max_cpus: 8, max_memory_mb: 16384, max_disk_mb: 102400, max_idle_timeout_secs: 86400}
network:
  default: {mode: allowlist, allow: [github.com, registry.npmjs.org], deny: []}
  ceiling: allowlist
  may_allow: ["*.internal.example.com"]
pools:                                     # sandboxes booted ahead of time
  - {image: ghcr.io/you/sandbox-base:1, size: 2}

Where a backend cannot deliver what the policy asks — no root, so no network devices — the ceiling becomes none and the startup line says so, and a request for an allowlist is refused, never served open. Where it can filter by name but not offer open — Firecracker, always — an open default and ceiling become the allowlist, with the built-in list as the default. How the network default and the profiles interact is in self-hosting.md and security/README.md.

#What sandboxd refuses at startup

• A network address without a token, or without TLS.
• A token file other users can read.
• A policy file with an unknown key, or one that does not hold together: a default outside the limits, a default network the ceiling would refuse, a pool for an image the policy does not permit.
• --client-ca without --tls-cert and --tls-key.
• A --metrics-listen address that is not loopback.
• --keep-sandboxes with a backend that cannot keep sandboxes, and a records directory other users can read.

#Node endpoints

GET /v1/node reports the node's capacity, what is free (capacity less what every sandbox not terminated, pooled ones included, has been given), how many run, the pools by image, the images whose disks are already built, the labels and whether it is cordoned. POST /v1/node/cordon with {"cordoned": true} stops new sandboxes landing on the node (503 unavailable) while those already there carry on. A cordon is held in memory, so a restart clears it. Both are for a gateway; a gateway does not proxy them to users (api/v1.md).

#Metrics

--metrics-listen 127.0.0.1:9100 serves Prometheus metrics at /metrics: sandboxes by state, processes running, pool sizes by image, capacity and free, cordon, and creates by status with a latency histogram. It has no credential, so sandboxd refuses any address but loopback; put a proxy with its own authentication in front if the scraper is elsewhere. The names are listed in operations.md.

#Files