#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.

#Private images

A pull is anonymous unless the create asks for it with a login (registry_login, api/v1.md). sandboxd keeps no login of its own: one it held would let every user of the node start from what it pulled. Behind a gateway, each organization keeps its logins there (sandbox-cli registry login ghcr.io -u USER < token, or Studio's Secrets page), and the gateway adds the right one to that organization's creates.

• A login is used only for its registry, sent only in the token request the registry's challenge points to, over https (or an --insecure-registry), and never logged or put in an error.
• The pull tokens and the manifests sandboxd keeps for an offline start are kept per login, so a create without the login meets the registry's refusal, even for an image already on the node: the manifest is fetched for every create, and the cached layers are reached only through it.
• An anonymous pull the registry refuses says so; one with a login says the login was refused (on ghcr.io a token needs read:packages and access to the package).
• Firecracker only (capability registry_login). The macos backend pulls through the container runtime and refuses a create carrying a login: log the runtime in with container registry login instead.

#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.
• GPU flags that would do half a thing: --gpu with the firecracker backend but without both --cloud-hypervisor and --gpu-kit (or either without --gpu), a --gpu that is not a PCI address or is given twice, and any of them on the macOS backend. A GPU not bound to vfio-pci is only logged at startup; each create checks it again.

#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.

A sandbox's own usage is not here: its owner can have it pushed to their collector with its metrics export.

#Files