# spawnd

> spawnd is an AI sandbox hosting platform: agents create secure Firecracker microVMs over a REST API, run untrusted code inside them, and are billed by the second of allocated VM usage (resource-seconds). The primary consumer is a machine, not a human. Base domain `spawnd.oonamy.xyz`; API prefix `/v1`; auth is an org API key (`Authorization: Bearer sk_live_...`).

## Docs

- [Full documentation (single-file markdown)](https://spawnd.oonamy.xyz/llms-full.txt): the complete API reference — auth, every endpoint with request/response shapes and curl examples, sizes, lifecycle, billing, errors, CLI, MCP. Read this to learn the whole API in one shot.
- [Human docs site](https://spawnd.oonamy.xyz/docs): the same content as a navigable web page.

## Auth

- Magic-link sign-in: `POST /auth/magic-link` → `GET /auth/verify?token=` issues a session JWT; `GET /auth/me` returns the profile. Dev mode returns the link inline as `devLink`.
- Session-authed key management: `GET /v1/keys`, `POST /v1/keys` (mints `sk_live_...`, shown once).
- Sandbox/SDK calls use the org API key; dashboard/key calls use the session JWT. The two are disjoint.

## Sandbox API (org API key)

- Create / list / get: `POST /v1/sandboxes`, `GET /v1/sandboxes`, `GET /v1/sandboxes/:id`.
- Run + files: `POST /v1/sandboxes/:id/exec`, `POST /v1/sandboxes/:id/files`, `GET /v1/sandboxes/:id/files?path=`.
- Networking: `POST /v1/sandboxes/:id/ports` returns a preview URL at `<id>.spawnd.oonamy.xyz`.
- Lifecycle: `POST /v1/sandboxes/:id/pause`, `POST /v1/sandboxes/:id/resume`, `POST /v1/sandboxes/:id/snapshot`, `POST /v1/sandboxes/:id/fork`, `POST /v1/sandboxes/:id/stop`, `DELETE /v1/sandboxes/:id`.
- Usage: `GET /v1/usage?from&to` returns resource-seconds (vCPU-s + GiB-s).

## Concepts

- Sizes (RAM GiB = vCPU × 2): `smallbox`/`base` (1 vCPU / 2048 MiB), `box`/`default` (2 / 4096), `bigbox` (4 / 8192), `megabox` (8 / 16384). Allocation is fixed at create and drives billing; an unknown name is rejected with `invalid_argument`.
- Lifecycle verbs: create, start, exec, snapshot, fork, pause, resume, stop, kill. All idempotent. States: creating, running, paused, stopping, stopped, killed (+ transient snapshotting, forking); killed is terminal.
- Billing: resource-seconds = vCPU-seconds (`vcpu × s`) + GiB-seconds (`memMib/1024 × s`), on the create-time allocation. Running bills at the `active` rate; paused at the cheaper `paused` rate.
- Isolation: microVM + jailer + per-VM network namespace. Guest code cannot reach the host, the control plane, or another sandbox.
- Errors: `{ code, message, retryable }` with codes `unauthorized`, `not_found`, `invalid_state`, `quota_exceeded`, `capacity`, `guest_timeout`, `internal`.

## Other interfaces

- CLI: `spawn smallbox|bigbox|ls|exec|fork|rm` wraps the REST API.
- MCP server at `/mcp` (bearer org API key) exposes tools `spawn_sandbox`, `exec`, `read_file`, `write_file`, `expose_port`, `snapshot_sandbox`, `fork_sandbox`, `pause_sandbox`, `resume_sandbox`, `kill_sandbox`.
- Preview URLs: `<sandbox-id>.spawnd.oonamy.xyz` reverse-proxies to a chosen guest port; org-scoped and torn down with the VM.