sandboxed Documentation

Pages

1. OverviewWhat sandboxed exposes (sandboxd API, Traefik previews, runtimed tasks), runtime assumptions (Docker, Linux, SQLite), and the shortest create → task → preview path.
2. InstallationPrerequisites (Docker Engine + Compose on Linux), ./install.sh steps, .env bootstrap, base-image and control-plane build, compose up, and healthz/readyz verification.
3. QuickstartCopy-paste flow: POST /sandbox with ports, POST /v1/sandboxes/{id}/tasks, stream SSE events, open s-{id}-{port}.preview.{domain}, and optional env injection for provider keys.
4. Sandbox lifecycleSQLite-backed status machine (creating, running, stopped, error), container naming (s-{ulid}), reconcile-on-boot, and destroy vs purge semantics.
5. Preview routingTraefik Docker labels, Host rules (s-{id}-{port}.preview.{domain}), router priority 100 vs wake catch-all priority 1, PREVIEW_DOMAIN/ENTRYPOINT/TLS, and sandboxed.managed constraint.
6. Wake, idle, and pressureStop-on-idle (SANDBOXD_IDLE_THRESHOLD_SECONDS), wake-on-preview (catch-all → sandboxd), memory admission/refusal, pressure reaper, keepalive, and warming-page behavior.
7. Workspaces and isolationPer-sandbox bind mounts under SANDBOXED_DATA_DIR/workspaces, skeleton seeding, read-only rootfs and caps, memory/PID limits, userns=host default, and v1 storage trade-offs.
8. Run coding agentsSubmit tasks via POST /v1/sandboxes/{id}/tasks (prompt, agent default opencode), wake-on-submit, SSE on /events, env injection at create, and runtimed socket contract.
9. Manage sandboxesOperational workflows: create (ports, env, template), exec, keepalive, POST /v1/sandboxes/{id}/stop, DELETE vs POST purge, claim, and external-user purge hooks.
10. API authenticationService-token auth (SANDBOXD_API_TOKENS, Authorization: Bearer), SANDBOXD_API_AUTH_DISABLED rollback, SIGHUP env reload, loopback exemptions, and LAN exposure of SANDBOXED_API_BIND.
11. Private previewsvisibility=private sandboxes, Traefik forwardAuth to /forward-auth, preview tokens (SANDBOXD_PREVIEW_TOKEN_SECRETS), /preview-auth redirect flow, and deny modes.
12. Production deploymentWildcard DNS, traefik websecure + cert resolver, PREVIEW_TLS=true, enable API auth, hardening checklist (isolation, egress, disk), and scaling boundaries from README.
13. Control plane API (legacy)Internal /sandbox* routes: create/list/get, exec, keepalive, wake JSON, per-sandbox snapshots, purge/claim, healthz/readyz, metrics, GET /llm.txt integrator contract.
14. v1 API referencePublic /v1/sandboxes and /v1/snapshots: request/response shapes, error envelope (code, message, retryable), files CRUD, export zip, task lifecycle states, and template spin-up.
15. Configuration referenceCompose-backed env keys: preview domain/ports, SANDBOXED_DATA_DIR, API bind, auth tokens, idle/reaper/memory wake tuning, templates/library paths, and advanced cgroup toggles.
16. Preview URL referenceHostname pattern s-{ulid}-{port}.preview.{PREVIEW_DOMAIN}, HTTP_PORT suffix rules, localhost vs production HTTPS, and Traefik router/service naming.
17. runtimed referenceIn-sandbox supervisor HTTP over Unix socket: GET /status, POST /tasks, GET /tasks/{id}/events (SSE), POST /tasks/{id}/cancel; workspace paths and sandboxd runtime.Client bridge.
18. Health and metricsGET /healthz and /readyz semantics, Prometheus GET /metrics labels, audit/access logging paths, and docker compose logs for sandboxd and Traefik.
19. Build a todo app with an agentEnd-to-end recipe: create sandbox on port 3000, submit opencode task prompt, stream task events, verify preview URL, optional ANTHROPIC_API_KEY via env at create.
20. Exec a dev server previewRecipe without tasks API: POST /sandbox/{id}/exec to start a server on an exposed port, wake stopped sandboxes via preview hit, and curl with Host header locally.
21. Troubleshootingreadyz/docker socket failures, port 80 conflicts (HTTP_PORT), ULID validation, warming-page stalls, userns-remap seed errors, preview spin-up, and compose log probes.
22. Control plane developmentGo 1.22+ build/test/vet in control-plane/, CGO sqlite note, compose --build loop, package map (docker, store, reaper, wake, api), and image build cache behavior.
23. Uninstall and maintenanceuninstall.sh flags (--images, --data, --all), managed-container cleanup, workspace retention defaults, docker compose ps/logs/restart sandboxd, and backup paths for SQLite and workspaces.
24. ContributingProject layout, design constraints (Docker-only core, sqlite truth, docker CLI shell-out), issue report fields, and extension boundaries for integrators.