# sandboxed Documentation

> Reference for the self-hosted Docker control plane (sandboxd + Traefik) that provisions isolated dev sandboxes, coding-agent tasks, and preview URLs for AI app-builder backends.

This is a Grok-Wiki source-grounded repository documentation set. Use the complete Markdown link when an agent needs the full repo context.

## Context Links

- [Complete Markdown docs](https://grok-wiki.com/public/docs/tastyeffectco-sandboxes-f551c1a2e9a0/llms-full.txt)
- [Complete Markdown alias](https://grok-wiki.com/public/docs/tastyeffectco-sandboxes-f551c1a2e9a0.md)
- [Human interactive docs](https://grok-wiki.com/public/docs/tastyeffectco-sandboxes-f551c1a2e9a0)
- [GitHub repository](https://github.com/tastyeffectco/sandboxes)

## Repository

- Repository: tastyeffectco/sandboxes

- Generated: 2026-06-04T22:47:33.412Z
- Updated: 2026-06-04T23:08:46.182Z
- Runtime: Grok CLI
- Format: Documentation
- Pages: 24

## Pages

- [Overview](https://grok-wiki.com/public/docs/tastyeffectco-sandboxes-f551c1a2e9a0/pages/01-overview.md): What sandboxed exposes (sandboxd API, Traefik previews, runtimed tasks), runtime assumptions (Docker, Linux, SQLite), and the shortest create → task → preview path.
- [Installation](https://grok-wiki.com/public/docs/tastyeffectco-sandboxes-f551c1a2e9a0/pages/02-installation.md): Prerequisites (Docker Engine + Compose on Linux), ./install.sh steps, .env bootstrap, base-image and control-plane build, compose up, and healthz/readyz verification.
- [Quickstart](https://grok-wiki.com/public/docs/tastyeffectco-sandboxes-f551c1a2e9a0/pages/03-quickstart.md): Copy-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.
- [Sandbox lifecycle](https://grok-wiki.com/public/docs/tastyeffectco-sandboxes-f551c1a2e9a0/pages/04-sandbox-lifecycle.md): SQLite-backed status machine (creating, running, stopped, error), container naming (s-{ulid}), reconcile-on-boot, and destroy vs purge semantics.
- [Preview routing](https://grok-wiki.com/public/docs/tastyeffectco-sandboxes-f551c1a2e9a0/pages/05-preview-routing.md): Traefik 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.
- [Wake, idle, and pressure](https://grok-wiki.com/public/docs/tastyeffectco-sandboxes-f551c1a2e9a0/pages/06-wake-idle-and-pressure.md): Stop-on-idle (SANDBOXD_IDLE_THRESHOLD_SECONDS), wake-on-preview (catch-all → sandboxd), memory admission/refusal, pressure reaper, keepalive, and warming-page behavior.
- [Workspaces and isolation](https://grok-wiki.com/public/docs/tastyeffectco-sandboxes-f551c1a2e9a0/pages/07-workspaces-and-isolation.md): Per-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.
- [Run coding agents](https://grok-wiki.com/public/docs/tastyeffectco-sandboxes-f551c1a2e9a0/pages/08-run-coding-agents.md): Submit 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.
- [Manage sandboxes](https://grok-wiki.com/public/docs/tastyeffectco-sandboxes-f551c1a2e9a0/pages/09-manage-sandboxes.md): Operational workflows: create (ports, env, template), exec, keepalive, POST /v1/sandboxes/{id}/stop, DELETE vs POST purge, claim, and external-user purge hooks.
- [API authentication](https://grok-wiki.com/public/docs/tastyeffectco-sandboxes-f551c1a2e9a0/pages/10-api-authentication.md): Service-token auth (SANDBOXD_API_TOKENS, Authorization: Bearer), SANDBOXD_API_AUTH_DISABLED rollback, SIGHUP env reload, loopback exemptions, and LAN exposure of SANDBOXED_API_BIND.
- [Private previews](https://grok-wiki.com/public/docs/tastyeffectco-sandboxes-f551c1a2e9a0/pages/11-private-previews.md): visibility=private sandboxes, Traefik forwardAuth to /forward-auth, preview tokens (SANDBOXD_PREVIEW_TOKEN_SECRETS), /preview-auth redirect flow, and deny modes.
- [Production deployment](https://grok-wiki.com/public/docs/tastyeffectco-sandboxes-f551c1a2e9a0/pages/12-production-deployment.md): Wildcard DNS, traefik websecure + cert resolver, PREVIEW_TLS=true, enable API auth, hardening checklist (isolation, egress, disk), and scaling boundaries from README.
- [Control plane API (legacy)](https://grok-wiki.com/public/docs/tastyeffectco-sandboxes-f551c1a2e9a0/pages/13-control-plane-api-legacy.md): Internal /sandbox* routes: create/list/get, exec, keepalive, wake JSON, per-sandbox snapshots, purge/claim, healthz/readyz, metrics, GET /llm.txt integrator contract.
- [v1 API reference](https://grok-wiki.com/public/docs/tastyeffectco-sandboxes-f551c1a2e9a0/pages/14-v1-api-reference.md): Public /v1/sandboxes and /v1/snapshots: request/response shapes, error envelope (code, message, retryable), files CRUD, export zip, task lifecycle states, and template spin-up.
- [Configuration reference](https://grok-wiki.com/public/docs/tastyeffectco-sandboxes-f551c1a2e9a0/pages/15-configuration-reference.md): Compose-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.
- [Preview URL reference](https://grok-wiki.com/public/docs/tastyeffectco-sandboxes-f551c1a2e9a0/pages/16-preview-url-reference.md): Hostname pattern s-{ulid}-{port}.preview.{PREVIEW_DOMAIN}, HTTP_PORT suffix rules, localhost vs production HTTPS, and Traefik router/service naming.
- [runtimed reference](https://grok-wiki.com/public/docs/tastyeffectco-sandboxes-f551c1a2e9a0/pages/17-runtimed-reference.md): In-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.
- [Health and metrics](https://grok-wiki.com/public/docs/tastyeffectco-sandboxes-f551c1a2e9a0/pages/18-health-and-metrics.md): GET /healthz and /readyz semantics, Prometheus GET /metrics labels, audit/access logging paths, and docker compose logs for sandboxd and Traefik.
- [Build a todo app with an agent](https://grok-wiki.com/public/docs/tastyeffectco-sandboxes-f551c1a2e9a0/pages/19-build-a-todo-app-with-an-agent.md): End-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.
- [Exec a dev server preview](https://grok-wiki.com/public/docs/tastyeffectco-sandboxes-f551c1a2e9a0/pages/20-exec-a-dev-server-preview.md): Recipe 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.
- [Troubleshooting](https://grok-wiki.com/public/docs/tastyeffectco-sandboxes-f551c1a2e9a0/pages/21-troubleshooting.md): readyz/docker socket failures, port 80 conflicts (HTTP_PORT), ULID validation, warming-page stalls, userns-remap seed errors, preview spin-up, and compose log probes.
- [Control plane development](https://grok-wiki.com/public/docs/tastyeffectco-sandboxes-f551c1a2e9a0/pages/22-control-plane-development.md): Go 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.
- [Uninstall and maintenance](https://grok-wiki.com/public/docs/tastyeffectco-sandboxes-f551c1a2e9a0/pages/23-uninstall-and-maintenance.md): uninstall.sh flags (--images, --data, --all), managed-container cleanup, workspace retention defaults, docker compose ps/logs/restart sandboxd, and backup paths for SQLite and workspaces.
- [Contributing](https://grok-wiki.com/public/docs/tastyeffectco-sandboxes-f551c1a2e9a0/pages/24-contributing.md): Project layout, design constraints (Docker-only core, sqlite truth, docker CLI shell-out), issue report fields, and extension boundaries for integrators.

## Source Files

- `.env.example`
- `AGENTS.md`
- `ARCHITECTURE.md`
- `CONTRIBUTING.md`
- `control-plane/cmd/runtimed/server.go`
- `control-plane/cmd/runtimed/task.go`
- `control-plane/cmd/sandboxd/main.go`
- `control-plane/Dockerfile`
- `control-plane/go.mod`
- `control-plane/internal/api/api.go`
- `control-plane/internal/api/external_purge.go`
- `control-plane/internal/api/forward_auth.go`
- `control-plane/internal/api/handlers.go`
- `control-plane/internal/api/llmtxt.go`
- `control-plane/internal/api/preview_auth.go`
- `control-plane/internal/api/taskwatch.go`
- `control-plane/internal/api/v1_files_write.go`
- `control-plane/internal/api/v1_files.go`
- `control-plane/internal/api/v1_snapshots.go`
- `control-plane/internal/api/v1_tasks.go`
- `control-plane/internal/api/v1.go`
- `control-plane/internal/audit/audit.go`
- `control-plane/internal/auth/config.go`
- `control-plane/internal/auth/middleware.go`
- `control-plane/internal/auth/preview_token.go`
- `control-plane/internal/auth/token.go`
- `control-plane/internal/docker/docker.go`
- `control-plane/internal/egress/nftables.go`
- `control-plane/internal/loopback/loopback.go`
- `control-plane/internal/metrics/metrics.go`
- `control-plane/internal/reaper/idle.go`
- `control-plane/internal/reaper/pressure.go`
- `control-plane/internal/reconcile/reconcile.go`
- `control-plane/internal/runtime/client.go`
- `control-plane/internal/store/store.go`
- `control-plane/internal/store/writer.go`
- `control-plane/internal/traefik/traefik.go`
- `control-plane/internal/wake/handler.go`
- `control-plane/migrations/0001_init.sql`
- `control-plane/migrations/0005_tasks.sql`
- `control-plane/migrations/0009_snapshots.sql`
- `control-plane/README.md`
- `docker-compose.yml`
- `image/build.sh`
- `image/Dockerfile`
- `image/HOME_LAYOUT.md`
- `image/README.md`
- `image/skel/.profile`
- `install.sh`
- `LICENSE`
- `README.md`
- `traefik/dynamic/auth.yml`
- `traefik/dynamic/wake.yml`
- `traefik/traefik.yml`
- `uninstall.sh`