Skip to main content

[ INTRO ]

What is sandboxd?

sandboxd turns one ordinary server into a fleet of isolated dev environments — each with its own filesystem, its own memory limits, an AI coding agent pre-installed, and a live preview URL. Self-hosted, open-source, installed in one command.

You send it one HTTP request, and it:

  1. Creates a sandbox — a private, isolated Linux container, so one user's (or one agent's, or one branch's) code can never see or break another's.
  2. Runs code or an AI coding agent inside it — exec any command, write files through the API, or hand it a prompt and let an agent build. (The OpenCode and Claude Code CLIs come pre-installed.)
  3. Gives whatever runs inside a live URL — the dev server running in the sandbox is instantly reachable at a shareable preview link, with routing and TLS handled for you.
POST /sandbox          → a private, isolated container spins up
POST .../tasks         → an AI agent writes an app inside it
http://<id>.preview... → that app is live at its own URL

It's also cheap to run: a sandbox goes to sleep when nobody's using it (freeing memory) and wakes up the instant someone opens its link again — files are saved on disk the whole time. So one ordinary server can hold many users, agents, or branches instead of needing one virtual machine each.

Under the hood it's deliberately small and easy to understand: one Go program that tells Docker what to do, with Traefik handling the URLs and SQLite as the database. No Kubernetes, no separate database server, no message queue — you could read the whole thing in an afternoon.

            ┌──────────────── your host (just needs Docker) ────────────────┐
 browser ──▶│  Traefik  ──▶  sandbox  (coding agent + dev server :3000)      │
            │     ▲              ▲   ▲                                        │
 API/CLI ──▶│  sandboxd ─────────┘   └─ workspace dir (persists)             │
            │     │  SQLite (source of truth) · idle→stop · request→wake      │
            └─────┴────────────────────────────────────────────────────────-─┘

What people run on it​

sandboxd is a building block, not a single-purpose product. The same create → build → preview → sleep → wake loop powers very different things:

  • AI app-builder products — the apps where a user types "build me a todo app" and a working website appears at its own link, like Lovable, Bolt, v0, or Replit. sandboxd is the open-source backend that makes that possible, on your own server.
  • Agent platforms and internal agent runs — give every coding agent its own isolated workspace with a real lifecycle: submit a prompt, stream progress over SSE, capture a durable result. Inject your own provider keys per sandbox; nothing leaves your infrastructure.
  • Per-user or per-branch preview environments — every developer, branch, or pull request gets a live, shareable URL that survives reboots and costs nothing while idle.
  • Coding playgrounds — hand out disposable, resource-capped environments where one user can't take down the rest.
  • Multi-app hosting for a team — run many small internal apps on one box, each at its own clean URL, each stopping when idle and waking on the next request.

Because it's self-hosted and MIT-licensed, it fits where SaaS sandboxes can't: your code, your data, and your API keys stay on hardware you control — whether that's a $20 VPS or a server inside your company's network.

Who's it for?​

✅ Use it if you're running many sandboxes — for users of your product, for your team, or for your agents: an AI app-builder, an agent platform, a coding playground, per-user or per-branch preview environments, or multi-app hosting for a team.

❌ Skip it if you just need one or two containers for yourself — a shell script, docker run, or lxd is simpler. (More on that below.)

Why sandboxd?​

Whether you're shipping an AI product or building an internal platform, the hard part isn't the prompt or the app — it's the infrastructure underneath it:

  • Multi-tenant isolation so one user's code can't touch another's.
  • Per-user preview URLs with automatic routing and TLS.
  • Cost control — idle environments must release memory, or your bill explodes.
  • Agent orchestration — run a coding agent against a workspace, stream its progress, capture the result.
  • Persistence, wake-on-demand, reconciliation after a crash or reboot.

That's months of platform work. sandboxd is that platform, distilled to one command:

  • ⚡ One-command install. ./install.sh and you have a working API + previews.
  • 🧠 Agents included. The OpenCode and Claude Code CLIs ship in every sandbox; hand a sandbox a prompt and it builds.
  • 💸 Dense by design. Stop-on-idle + wake-on-request means dozens of sandboxes share one box instead of one VM each — the difference between a $20 server and a $2,000 cluster.
  • 🔓 Yours. Self-hosted, MIT-licensed, no vendor lock-in. Own your data, your margins, and your roadmap.
  • 🪶 Boring on purpose. SQLite + the docker CLI + Traefik. A reconciler converges Docker back to the database on every boot. You can read the whole control plane in an afternoon.

"Why not just a shell script?"​

Fair question — and honestly: if you need one or two long-lived containers for yourself, a shell script (or docker run, or lxd) is simpler. Use that. We mean it. sandboxd is overkill for one-off projects.

It earns its keep the moment you're running many sandboxes for other people — a team, or a product — because that's when the tidy little docker run script quietly grows into all of this:

  • URLs, not ports. Every sandbox gets a clean preview URL with automatic routing + TLS — no port bookkeeping, no collisions to manage.
  • It sleeps and wakes itself. Idle sandboxes stop to free RAM and restart transparently on the next request (warming-up page, readiness probe, request hold). That part alone is well past 100 lines — and it's the difference between one cheap box and a rack of always-on VMs.
  • It survives reboots. SQLite is the source of truth; a reconciler re-converges Docker to it on boot. A script forgets everything when the host restarts.
  • It's an API, not a CLI you shell into. create / exec / stop / destroy / write-files / run-agent-task are real HTTP endpoints with auth — you call them from your app backend, your CI, or your scripts, per user, at scale.
  • One user can't take down the rest. Per-sandbox memory/PID limits + a host-memory pressure reaper.
  • Agents with a lifecycle. Submit a prompt, stream progress (SSE), capture a durable result — not just opencode fired inline.

Rebuild those as your script grows and you've rebuilt sandboxd. So: skip it for one-offs; reach for it when "just a script" has started keeping you up at night.

:::note Prefer Kubernetes?

The control plane talks to the container runtime through a thin docker CLI boundary, so a k8s Job/Pod backend is an interface swap, not a rewrite — a great first contribution. Today it targets a single Docker host (no k8s required), which is the sweet spot for teams who don't want to run a cluster just for sandboxes.

:::

Is this a good foundation for a product?​

Yes — that's exactly the point. If you want to ship an AI app-builder or agent SaaS — or stand up sandboxed environments inside your company — without first spending months building multi-tenant isolation, preview routing, idle/wake cost control, and agent orchestration, sandboxd gives you that core on day one, on a single inexpensive server, with margins you control. It's a strong, honest starting point — beta-quality, MIT-licensed, and built to be read and extended. Launch lean on it; harden as you grow (see Hardening).

Next steps​

License​

MIT. Use it, ship it, sell what you build on it.