Pairing fails
Use a fresh one-time token only inSANDBOX_PAIRING_TOKEN. Confirm the printed device fingerprint in the control plane. Verify HTTPS and runner clock before retrying.
If sudo reports sandbox-runner: command not found, extract the complete release archive and run sudo ./install.sh. The binary should then exist at /usr/local/bin/sandbox-runner. Pair it as the service user with sudo -u sandbox-runner env SANDBOX_PAIRING_TOKEN='…' /usr/local/bin/sandbox-runner --config /etc/sandbox-runner/config.toml pair; using the absolute path also avoids sudo PATH differences.
If the service reports that the runner is not paired after a successful pairing attempt, check that pairing was performed as sandbox-runner, not root, and that /var/lib/sandbox-runner/identity.json is owned by sandbox-runner. Re-running the packaged installer repairs ownership of the dedicated data directory without replacing the identity or config.
Runner is online but rejected
Routing diagnostics identify stale heartbeat, disabled/draining status, protocol or engine incompatibility, missing tag, wrong region, environment mismatch, runner capacity, or pool aggregate capacity. Do not remove a requirement merely to force selection.Command rejected locally
Check the control-plane signing key set, command expiry, nonce/time freshness, target runner/workspace/environment, revision content hash, required permission, connection restriction, and local allowlists. The human environment value must be development, staging, or production.Restart during work
The runner marks unfinished local execution failed and reportsrunner_restarted_before_completion. A previously completed durable receipt is acknowledged without re-execution. Lost-execution recovery may require manual review when an external side effect has uncertain outcome.
Maintenance
Drain first and give the service manager at least the configureddrain_timeout_seconds before killing the process.