Sandboxd: Self-Hosted Dev Sandboxes for AI Agents

Overview

appeared on GitHub Trending as an open-source project that provisions isolated development environments. It creates Docker containers on demand, runs AI coding agents inside them, and exposes live preview URLs through Traefik. The entire system runs on a single host with one command and uses SQLite for state. No Kubernetes cluster is required. The repository positions the tool as a backend for AI app builders that need per-user sandboxes.

Technical Implementation

sandboxd consists of a Go binary that manages Docker containers. Each sandbox receives its own filesystem, memory limits, and network isolation. When a POST request hits the control plane, the binary starts a container, mounts a persistent workspace directory, and registers a route with Traefik so the preview URL resolves immediately.

The project ships with docker-compose.yml, Traefik configuration, and install scripts. SQLite stores sandbox metadata and task status. Workspaces remain on disk even after containers stop, which allows the system to put idle sandboxes to sleep and resume them on the next request without data loss.

Two CLI tools, OpenCode and Claude Code, come pre-installed inside the base image. An external agent can therefore issue prompts that write files directly into the mounted workspace. The dev server inside the container then serves the application at the assigned preview domain.

Running It Locally

The install.sh script pulls the required images and starts the control plane. After startup, a single HTTP call creates a sandbox:

curl -X POST http://localhost:8080/sandbox

The response returns an identifier used for subsequent task requests. A second endpoint accepts prompts and routes them to the agent running inside the container. Preview URLs follow the pattern .preview. and are handled by Traefik’s dynamic routing.

Resource usage stays modest because containers share the host kernel and only active sandboxes consume memory. The architecture document notes that one mid-size server can support dozens of concurrent workspaces before CPU or disk becomes the bottleneck.

Practical Considerations

The single-host design removes orchestration complexity but also sets a hard limit on scale. Horizontal expansion requires either multiple independent instances or an external load balancer in front of several hosts. The current implementation does not include built-in authentication or multi-tenancy policies beyond container isolation.

Because everything runs through Docker on one machine, operators must handle host-level security, image updates, and disk cleanup themselves. The repository provides uninstall.sh for removal, yet production use still requires monitoring of container logs and workspace growth. For teams already comfortable with Docker and Traefik, the setup remains straightforward; others will need to learn those dependencies first.

FAQs

Does sandboxd require Kubernetes? No. It runs entirely with Docker and Traefik on a single host.

How are preview URLs generated? Traefik watches container labels and routes traffic to the internal dev server on port 3000 using the sandbox identifier as a subdomain.

Can sandboxes persist data across restarts? Yes. Workspace directories stay on the host filesystem while containers sleep and resume on demand.

---

📖 Related articles

• Agentic Coding: Una Trappola per lo Sviluppo Software?
• Claude Code: da prompt a agente con skills e subagent
• Lean-ctx: Ottimizzatore Ibrido Riduce Consumo Token LLM del 89-99%