sandboxd

sandboxd is the open-source backend that powers AI app-builder products like Lovable, Bolt, or Replit — self-hosted on your own server. Send it a single HTTP request and it creates a private, isolated Linux container, runs a coding agent inside it (OpenCode and Claude Code CLIs ship pre-installed), and exposes the running app at a shareable preview URL. All of this happens on one ordinary machine, not a Kubernetes cluster.

The platform is engineered for density and cost efficiency. Sandboxes stop automatically when idle, releasing their memory, and wake transparently the instant a user opens their preview link — files on disk are preserved the whole time. One affordable server can host dozens of active users instead of requiring a separate VM per tenant.

The control plane is deliberately minimal: a single Go binary that shells out to the Docker CLI, with Traefik handling edge routing and SQLite as the only database. No message queue, no separate database server, no orchestrator. The entire control plane can be read and understood in an afternoon, which makes self-hosting, auditing, and contributing straightforward for any Go-familiar developer.

sandboxd is MIT-licensed and ships production-ready hardening out of the box: each container gets a read-only rootfs, dropped capabilities, PID and file-descriptor limits, and a hard memory ceiling. A reconciler re-converges Docker to the SQLite source of truth on every boot, so a server restart never silently loses sandbox state.

What You Get

• A REST API that creates isolated Docker containers in seconds, each with its own workspace directory, memory ceiling, and preview URL automatically registered in Traefik
• Built-in OpenCode and Claude Code CLIs pre-installed in every sandbox so you can submit a coding prompt and stream the agent’s progress over Server-Sent Events
• Stop-on-idle and wake-on-request lifecycle management that lets dozens of sandboxes share one host without memory exhaustion, with a warming-up page served during the few seconds of restart
• SQLite-backed state with a boot-time reconciler that re-converges Docker to the database after crashes or reboots — no sandbox state is ever silently lost
• A file API for reading and writing workspace files programmatically, plus a workspace export endpoint for pulling completed projects out of the sandbox
• Token-based API auth with SIGHUP hot-reload, Prometheus metrics on every endpoint, structured JSON logging, and optional Traefik forward-auth for private preview URLs

Common Use Cases

• Building an AI app-builder product where users describe what they want and receive a live, shareable URL to the running app within seconds
• Providing per-branch or per-PR preview environments for a development team without provisioning a virtual machine per environment
• Running a coding playground or internal developer portal where each user gets their own isolated workspace that persists between sessions
• Operating an agent platform that needs to run untrusted or AI-generated code in isolation, stream the execution output, and expose the result at a URL
• Hosting multiple small SaaS apps for a team on a single server with automatic traffic routing and idle-cost management instead of always-on VMs

Under The Hood

Architecture The control plane follows a clear layered architecture with a single daemon binary coordinating multiple independent subsystems — a reconciler, two reapers, an access-log tailer, a connection poller, a wake handler, and an HTTP mux — each wired together at startup through explicit dependency injection. The design philosophy is “SQLite is source of truth, Docker is derived state”: all mutations go through a serialized single-writer goroutine in the store package, and a reconciler converges Docker back to the database on every boot. Separation of concerns is enforced at the package boundary — the store knows nothing about Docker, the reaper knows nothing about routing, and the wake handler knows nothing about the task subsystem. The in-sandbox supervisor is a separate binary built into the base image, communicating with the control plane over a Unix domain socket, which cleanly isolates container-side logic from host-side orchestration.

Tech Stack The control plane is written in Go 1.22 using only the standard library plus three production dependencies: go-sqlite3 for the database layer in WAL mode, the oklog ULID library for sandbox ID generation, and the Prometheus Go client for metrics. There is no web framework — routing uses Go 1.22’s enhanced net/http ServeMux with method-and-pattern matching directly. Docker interaction shells out to the docker CLI binary rather than using the Docker SDK, keeping the dependency surface minimal. Traefik v3 serves as the edge proxy using its Docker label provider for dynamic routing, with a file-provider catch-all for the wake path. The sandbox base image ships Node.js, Python, Bun, pnpm, and two coding agent CLIs (OpenCode and Claude Code) pre-installed on a Debian base.

Code Quality The codebase has comprehensive test coverage across the core packages: unit tests exist for API ID validation, file-write handlers, task-watch logic, store idle policies and task state transitions, the auth preview-token implementation, the nginx watcher, the Traefik label builder, and the runtime client. Tests use standard Go testing with table-driven patterns. Error handling is explicit throughout — errors are wrapped with context using fmt.Errorf and returned up the call stack rather than swallowed; the main loop logs errors and continues or exits with explicit codes. Inline comments are extensive and explain not just what the code does but why design decisions were made, including references to an explicit non-negotiables list and phased development history. The code style is consistent across all packages.

What Makes It Unique What distinguishes sandboxd is the combination of stop-on-idle / wake-on-request density management with an integrated in-sandbox agent supervisor, packaged as a single-binary control plane that requires only Docker. The wake path is technically novel: Traefik’s priority system means a stopped sandbox has no high-priority router, so requests fall through to a sandboxd catch-all that starts the container, polls the TCP port, serves a styled warming-up page, and yields to Traefik’s newly registered high-priority router on the next browser refresh — all without redirects or DNS changes. The runtimed in-sandbox supervisor is a second innovation: a Go binary compiled into the base image that provides a Unix-socket HTTP API for task submission, SSE event streaming, and dev-server health probing, completely decoupling the host control plane from the specific coding agents or dev servers running inside the container.

Self-Hosting

sandboxd is released under the MIT License, which is one of the most permissive open-source licenses available. You may use it commercially, modify the source, redistribute it, and incorporate it into proprietary products without any copyleft obligations. The only requirement is that the copyright notice and license text are preserved in distributions. There is no open-core model, no enterprise license tier, and no feature flag separating a community edition from a paid one — the repository you clone is the complete product.

Running sandboxd yourself requires a Linux host with Docker Engine and the Compose plugin installed. The install script handles the rest: it writes an environment file, builds the sandbox base image and the control plane binary, and starts the stack. On the operational side, you are responsible for host patching, Docker daemon health, disk space under the workspaces directory, and SQLite database backups (a simple file copy of sandboxd.db suffices). The reconciler recovers Docker state from SQLite on every restart, so reboots are safe, but there is no built-in high-availability or multi-host clustering — the control plane is intentionally scoped to a single Docker host. Scaling horizontally means running multiple independent sandboxd instances behind your own load balancer.

Compared to a managed sandbox hosting service, self-hosting sandboxd means you own the data and the margins, but you also carry the operational burden: no managed TLS certificate renewal beyond the Traefik Let’s Encrypt integration you configure yourself, no SLA, no on-call support, and no automated security patching of the base image. The project is in early beta with active development; expect breaking changes between minor versions. Snapshots and workspace templates are present in the API but marked experimental. If you need a fully managed multi-tenant sandbox service with guaranteed uptime and support contracts, a cloud-hosted alternative is the more appropriate choice for now.