sandboxes

What is sandboxed? (start here)

Think of the apps where you type "build me a todo app" and seconds later a working website appears at its own link — like Lovable, Bolt, v0, or Replit. sandboxed is the open-source backend that makes that possible, running on your own server.

Here's what it does, in plain terms. You send it one HTTP request, and it:

1. Creates a sandbox — a private, isolated Linux container (its own filesystem, its own memory limits), so one user's code can never see or break another's.
2. Runs an AI coding agent inside it — you give it a prompt, and it writes the code into that sandbox. (The OpenCode and Claude Code CLIs come pre-installed.)
3. Gives the app a live URL — the dev server running inside the sandbox is instantly reachable at a shareable preview link.

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 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      │
            └─────┴────────────────────────────────────────────────────────-─┘

Who's it for?

✅ Use it if you're running many sandboxes for other people — an AI app-builder ("describe an app → see it live"), 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 sandboxed?

If you're building an AI app-builder, an agent platform, a coding playground, or a per-user preview product, the hard part isn't the prompt — 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. sandboxed 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. sandboxed 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, 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 sandboxed. So: skip it for one-offs; reach for it when "just a script" has started keeping you up at night.

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.

Quick start

Requirements: Docker Engine + the Compose plugin, on Linux. That's it.

1. Install

git clone https://github.com/tastyeffectco/sandboxes.git
cd sandboxes
./install.sh

install.sh checks Docker, writes a .env, builds the sandbox base image + the control plane, and starts the stack. The API is then live at http://127.0.0.1:9090 (verify: curl http://127.0.0.1:9090/healthz → ok).

2. Have an agent build an app

The base image already includes the OpenCode and Claude Code CLIs. Hand a sandbox a prompt and watch it build (OpenCode runs on its free plan out of the box; pass your own provider key via env to use your account):

API=http://127.0.0.1:9090

# create a sandbox that will serve on port 3000
ID=$(curl -s -XPOST $API/sandbox -H 'content-type: application/json' \
       -d '{"ports":[3000]}' | sed -E 's/.*"id":"([^"]+)".*/\1/')
echo "sandbox: $ID"

# spin a coding agent with a request — it works in ~/workspace/app
curl -s -XPOST $API/v1/sandboxes/$ID/tasks -H 'content-type: application/json' -d '{
        "prompt":"create a Vite app that shows a todo list and run it on port 3000",
        "agent":"opencode"
     }'
# -> {"id":"<taskId>","status":"running","events_url":"/v1/sandboxes/<id>/tasks/<taskId>/events"}

# stream the agent's progress (Server-Sent Events)
curl -N $API/v1/sandboxes/$ID/tasks/<taskId>/events

To use your own model account instead of the free plan, inject a key at create time — it's available to the agent and any shell in the sandbox:

curl -s -XPOST $API/sandbox -d '{"ports":[3000],"env":{"ANTHROPIC_API_KEY":"sk-ant-..."}}'

3. Open the live preview

Once the app serves on port 3000, it's reachable at its preview URL — the sandbox self-registered the route, nothing else to wire:

http://s-<id>-3000.preview.localhost

*.localhost resolves to 127.0.0.1 in every modern browser, so it works locally with zero DNS and zero certificates (add :$HTTP_PORT if you changed it from 80). The first request to a stopped sandbox wakes it automatically. On a real domain you get https://s-<id>-3000.preview.yourdomain.com (see Production / TLS).

Just want a shell, no agent? Skip step 2 and run anything via the exec API: curl -XPOST $API/sandbox/$ID/exec -d '{"cmd":["bash","-lc","cd ~/workspace/app && python3 -m http.server 3000"]}' then open the same preview URL.

API

Base URL = http://127.0.0.1:9090 (set by SANDBOXED_API_BIND). Auth is off by default for local use; with SANDBOXD_API_AUTH_DISABLED=false + SANDBOXD_API_TOKENS, send -H "Authorization: Bearer <secret>".

| Method & path | Body | Purpose | |---|---|---| | POST /sandbox | {"ports":[3000],"env":{...}} | create — id optional (ULID auto); env injects vars (e.g. API keys) | | GET /sandboxes | — | list all sandboxes | | GET /sandbox/{id} | — | get one (status, ports, container id…) | | POST /sandbox/{id}/exec | {"cmd":["bash","-lc","…"]} | run a command (non-interactive) | | POST /sandbox/{id}/keepalive | — | postpone the idle reaper | | POST /v1/sandboxes/{id}/stop | — | stop now to free RAM (wakes