Drukbox is a FastAPI service that provisions sandbox hosts.

Sandbox and VM providers are many and change quickly. Drukbox keeps them behind a stable API: each provider is an adapter, so switching or adding one is a config change, not a migration.

It owns the sandbox lifecycle end to end: host records and state in Postgres, inline provisioning in POST /hosts, provider VM creation and teardown, optional Tailscale networking, and the ssh-keyscan material callers need to connect. It hands back SSH coordinates and stops there — drukbox does not speak SSH and does not own a runtime inside the VM.

No provider account needed: run Drukbox from source on the host, so the docker provider can reach the local Docker daemon and run sandboxes as local containers:

git clone https://github.com/czpython/drukbox.git
cd drukbox && uv sync
export SECRETS_KEY="$(uv run python -c 'import base64, os; print(base64.b64encode(os.urandom(32)).decode())')"
make dev

Then create a sandbox from another terminal:

curl -fsS -H "Authorization: Bearer dev-token" \
  -X POST http://localhost:8000/hosts

The response includes the SSH host, port, username, private key, and known_hosts material needed to connect. A running service also serves interactive API docs at http://localhost:8000/docs.

• API — endpoints, auth, and the OpenAPI reference.
• Architecture — the broker model, boundaries, the provider contract, capabilities, lifecycle.
• Networking — Tailscale vs public path, key material, security groups, known_hosts.
• Deploy — image, cron jobs, migrations, IAM, and the full configuration reference.
• Security — trust model, auth, secret and metadata handling, and the tradeoffs behind each default.
• Add a provider — integrating a new VM provider.

uv sync
uv run ruff check
uv run ruff format --check
uv run pyright
uv run pytest

uv run pytest loads non-secret test settings from env/test.env via src/conftest.py; CI runs the same checks plus a Docker image build.

api-tests/ is a Playwright black-box suite for an already-running deployment — it provisions a real host, so point it at disposable infrastructure only (see Deploy).