sandboxd: A self-hosted AI app builder that runs agents in Docker sandboxes on your own server

What sandboxd actually does

The architecture is deliberately minimal. One Go program drives Docker, Traefik handles URL routing, and SQLite stores state. There is no Kubernetes, no separate database, and no queue. This is a conscious trade-off. You get a system that is easy to understand and operate, but you also inherit the limitations of a single Docker daemon and a single SQLite file. If you need horizontal scaling or multi-tenant isolation at the kernel level, this design will not give it to you.

How the sandbox lifecycle works

The preview URL pattern is also visible in the API example. When you create a sandbox with a port, the resulting app appears at a URL like `http://s-$ID-3000.preview.localhost`. Traefik is the component that maps these hostnames to the correct container. This is a concrete mechanism, and it is the same pattern used by many local development tools. The dependency on `preview.localhost` means your DNS and Traefik configuration must be correct for the URLs to work, which is a real operational detail to verify during setup.

Two ways to use it: API-first or web console

The console is not a separate product. It is a client that talks to the same API. This is a clean design because it means every feature available in the console is also available programmatically. The README says the console is the fastest way to get started, but the API is the foundation. If you plan to use sandboxd as a backend, you are not building against a second-class interface. That is a point in its favor.

Getting it running: commands and configuration

For headless operation, you set `SANDBOXD_CONSOLE=0` or pass `--no-console`. The API listens on `http://127.0.0.1:9090`, and a health check is available at `/healthz`. The README shows a full API workflow: first you set an agent API key, then create a sandbox with a port, then send a prompt. The example uses `agent: "opencode"`, and the URL for the running app follows the pattern `http://s-$ID-3000.preview.localhost`. Upgrades are handled by `./upgrade.sh`, which backs up the database first, health-checks the new version, and rolls back automatically on failure. The `--check` flag shows your current version. These are concrete commands you can run, and they give a sense of how the project approaches operational safety.

What you can run inside a sandbox

This is a broad claim, and the actual support quality will depend on how well the curated app definitions are maintained. The README does not list the full catalog or the exact presets available. For a team evaluating this, the practical test is to pick a few apps you actually need and verify they install cleanly. The claim that "if it's open-source, you can almost certainly run it" is marketing language. The honest constraint is that the agent must be able to work within the sandbox's filesystem and network limits, and the base image must be compatible with your host architecture. The README says images build from multi-arch bases, so arm64 and amd64 are both supported, which is a real advantage for ARM servers.

Known limitations and wrong-tool cases

The "best-effort" support for macOS is a red flag for local development. If you are on an Apple Silicon Mac, you can run it, but you should expect to debug Docker networking issues. The README also says nothing about resource limits for the agent itself, so a runaway agent could consume all available CPU or memory on the host. The sleep and wake mechanism helps, but it does not replace proper cgroup limits.

Alternatives and how they differ

A closer alternative in the open-source space would be something like a self-hosted agent runner or a container-based dev environment platform, but the README does not name any. What I can say from the material is that sandboxd is positioned as a complete engine, not a thin wrapper. It includes Docker orchestration, URL routing, state persistence, and an agent API. That is a different scope from a tool that only runs an agent in a container. For a team that already uses Kubernetes, a more natural fit might be a Kubernetes-native agent runner, but sandboxd explicitly avoids Kubernetes to stay simple. That is a deliberate trade-off, and it will appeal to some and frustrate others.

Maintenance, licensing, and upgrade path

The upgrade script is a notable maintenance feature. It backs up the SQLite database before applying a new version, health-checks the result, and rolls back automatically if something fails. That is a concrete mechanism that reduces the risk of a bad upgrade. The `--check` flag lets you see your current version before deciding to upgrade. The release history shows active development, with three releases on the same day (v0.3.18, v0.3.19, v0.3.20), which suggests a fast iteration cadence. That is good for bug fixes but also means you should expect frequent changes. The README does not mention a stable API guarantee or a deprecation policy, so you should pin a version and test upgrades in a staging environment before applying them to production.

Editorial conclusion

Adopt sandboxd if you want an AI app builder that keeps every byte of code and data on your own hardware, and you are comfortable running a Docker-based stack without Kubernetes or a separate database. Skip it if you need a managed service with zero infrastructure upkeep, or if your workloads demand per-tenant isolation beyond a single Docker daemon. Before adopting, verify that your server meets the Docker requirement, test the installer on your exact Linux distribution, and confirm that the agent integrations you plan to use (Claude Code, opencode, others) are supported. Then run the installer, check the health endpoint, and create one sandbox with a trivial prompt to confirm the preview URL routing works on your network.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes