HTTP API

crucible is driven entirely over HTTP. This is the reference for the daemon's REST surface.

• Base URL: whatever you pass to --listen (default http://127.0.0.1:7878).
• Authentication. Off by default on loopback; required as soon as any API key exists. Pass Authorization: Bearer <key>. See Authentication below and SECURITY.md.
• Content type: requests and responses are JSON, except the exec stream (see below). Request bodies are size-capped; oversized bodies are rejected.
• Errors: any non-2xx JSON response has the shape {"error": "message"}.

IDs are validated on every path; a malformed sandbox or snapshot ID returns 400 before any work happens.

Authentication

The daemon supports bearer-token API keys, on the same model as the Docker or Kubernetes CLIs.

• Loopback default: no auth. With no keys configured, the daemon (bound to 127.0.0.1) serves every request unauthenticated — the single-operator local case.
• Enabling auth. Create a key with crucible daemon token add --name <label>. The raw key is printed once (crucible_…); only its SHA-256 hash is stored. As soon as one key exists, every request must carry Authorization: Bearer <key> or it is rejected 401 with a WWW-Authenticate: Bearer header. Manage keys with crucible daemon token list / revoke <id> (rotate = add a new key, then revoke the old); changes take effect without a daemon restart.
• /healthz is always exempt, so liveness probes work without a key.
• Binding non-loopback requires auth + TLS. The daemon refuses to bind a non-loopback address unless at least one key exists and --tls-cert/--tls-key are set. Clients send the key over TLS with --token / CRUCIBLE_TOKEN.

Endpoints

The image, service, and logs endpoints answer 501 when the daemon is started without the corresponding subsystem (--image-dir, a service-capable rootfs, --log-dir). Calling a known path with an unsupported method returns 405.

GET /healthz

Returns 200 with {"status": "ok"} once the daemon is serving. No side effects.

GET /metrics

Prometheus metrics in the standard text exposition format. Label-free today:

Like the rest of the API, /metrics is subject to auth when keys are configured (only /healthz is exempt) and is loopback-bound by default — scrape it from a colocated agent (with a token if auth is on), not across a trust boundary.

GET /profiles

Returns the rootfs profiles the daemon was configured with via --rootfs-dir, sorted (empty when none):

{ "profiles": ["base", "node-22", "python-3.12"] }

These are the values accepted by the profile field of POST /sandboxes. See profiles.md.

POST /sandboxes

Create a sandbox. All fields are optional — an empty body {} boots a sandbox with daemon defaults.

{
  "vcpus": 1,
  "memory_mib": 512,
  "boot_args": "",
  "timeout_s": 0,
  "network": {
    "enabled": true,
    "allowlist": ["pypi.org", "*.npmjs.org"]
  }
}

Network policy. When network is present, enabled: true requires a non-empty allowlist; unrestricted full-internet egress is not offered by design (default-deny is the model). Each allowlist entry is an exact hostname (pypi.org) or a single-label wildcard (*.npmjs.org); a bare * is rejected. enabled: false with a populated allowlist is a 400 (inconsistent).

Response 201 Created:

{
  "id": "sbx_7k2m...",
  "vcpus": 1,
  "memory_mib": 512,
  "workdir": "/tmp/crucible/run/sbx_7k2m...",
  "created_at": "2026-01-01T00:00:00Z",
  "network": {
    "enabled": true,
    "guest_ip": "10.20.0.2",
    "gateway": "10.20.0.1",
    "allowlist": ["pypi.org", "*.npmjs.org"]
  }
}

network is omitted when the sandbox has no NIC; profile is echoed back when the sandbox booted from a named profile. Errors: 400 (invalid JSON or config, including an unknown profile), 501 (image set), 500 (boot failure).

GET /sandboxes

Returns 200 with {"sandboxes": [ <sandbox>, ... ]} (empty array when none). Each element has the same shape as the create response.

GET /sandboxes/{id}

Returns 200 with the sandbox object, 404 if unknown, 400 on a malformed ID.

DELETE /sandboxes/{id}

Tears down the VM and reclaims its resources. Returns 204 No Content on success, 404 if unknown.

POST /sandboxes/{id}/exec

Run a command inside the sandbox and stream its output. Request body:

{
  "cmd": ["pytest", "/app/tests"],
  "env": { "CI": "1" },
  "cwd": "/app",
  "timeout_s": 120
}

Validation errors (bad JSON, empty cmd, unknown sandbox) come back before streaming as a normal 4xx JSON error. Once validation passes the daemon sends 200 with Content-Type: application/octet-stream and streams a frame protocol:

• Each frame = an 8-byte header (1 type byte, 3 reserved bytes, a big-endian uint32 payload length) followed by the payload.
• Response frame types: 1 = stdout, 2 = stderr, 3 = exit.
• stdout/stderr data frames arrive as the command runs; the final exit frame's payload is the ExecResult JSON.

Because the 200 is committed before the command finishes, a failure after streaming starts (agent unreachable, dropped connection) is delivered in-band as an exit frame with exit_code: -1 and a populated error — never as an HTTP error code.

Interactive exec (POST /sandboxes/{id}/exec?stdin=1). The one-shot path above is buffered. For a live shell, the daemon hijacks the connection into a full-duplex framed stream after the 200: the client sends inbound frames 4 = stdin and 5 = stdin-close (EOF), and reads the same stdout/stderr/exit frames back. State (cd, env) persists for the life of the long-lived process. This is what crucible shell <id> and sandbox exec -i use; it is line-buffered with no PTY. The one-shot path is unchanged.

Interactive exec over WebSocket (GET /sandboxes/{id}/exec + upgrade handshake). The same session for clients that can't hijack a raw connection (fetch-based runtimes, anything behind an L7 proxy). The client's first message is the JSON ExecRequest; after that, the concatenated binary message payloads in each direction form exactly the same frame stream as the hijacked path — same byte layout, same frame types, so one frame codec serves both transports. Frames may split across WebSocket messages: decode the concatenated stream, not individual messages. Pre-upgrade failures (unknown sandbox) are plain HTTP errors on the handshake; post-upgrade validation failures close the socket with status 1008 and a reason. A plain GET without the upgrade handshake answers 426.

ExecResult (the exit-frame payload):

{
  "exit_code": 0,
  "duration_ms": 247,
  "signal": "",
  "timed_out": false,
  "oom_killed": false,
  "error": "",
  "usage": {
    "cpu_user_ms": 180,
    "cpu_sys_ms": 40,
    "peak_memory_bytes": 35389440,
    "page_faults_major": 2,
    "context_switches_involuntary": 14,
    "io_read_bytes": 0,
    "io_write_bytes": 0
  }
}

• exit_code is -1 when the process was killed by a signal or never started.
• signal is the signal name (e.g. "SIGKILL") when the process was signalled; empty on a clean exit.
• oom_killed is a best-effort heuristic (SIGKILL not from our timeout + peak RSS ≥ 95% of guest memory), not a precise cgroup reading.
• usage is null when the agent collected no stats (e.g. the process never started), so callers can tell "no data" from "zeroes". I/O counters are per-process and approximate for sub-100 ms commands (see the field docs in sdk/wire/exec.go).

POST /sandboxes/{id}/files and GET /sandboxes/{id}/files

File transfer between host and guest — one-way bulk copy, so no frame protocol.

Push (POST …/files?path=<dest>): the request body is a tar stream. The daemon streams it straight to the guest agent (nothing buffered whole); the agent MkdirAlls <dest> and extracts each entry beneath it, rejecting any entry whose resolved path escapes the destination (absolute paths, .., or symlinks pointing outside). Returns 200 {"files":N,"bytes":M}. Gated as an exec-class operation. This backs crucible cp (push) and the MCP write_files tool.

Read (GET …/files?path=<file>&max_bytes=<n>): returns the raw bytes of a single guest file (capped by max_bytes; a directory is a 400). This is a content read — only bytes flow out, nothing is written host-side, so it has no path-traversal surface. Gated as read. It backs the MCP read_file tool. Pulling a directory tree onto the host is intentionally not offered.

POST /sandboxes/{id}/snapshot

Pause the sandbox and write a snapshot (a VM state file + a guest-memory file) to disk. Returns 201 with:

{
  "id": "snp_...",
  "source_id": "sbx_7k2m...",
  "vcpus": 1,
  "memory_mib": 512,
  "dir": "/tmp/crucible/run/.../snap",
  "state_path": ".../state",
  "mem_path": ".../mem",
  "rootfs_path": ".../rootfs.ext4",
  "created_at": "2026-01-01T00:00:00Z"
}

The on-disk paths are returned for operator debugging (ls, du, debugfs). Errors: 404 (unknown sandbox), 500.

GET /snapshots / GET /snapshots/{id} / DELETE /snapshots/{id}

List ({"snapshots": [...]}), inspect (200 / 404), and delete (204 / 404) snapshots. Same object shape as the snapshot response above.

POST /snapshots/{id}/fork

Create sandboxes from a snapshot. Fan-out is set by the ?count=N query parameter (default 1); N must be a positive integer and is capped by the daemon's max fork count (400 if exceeded).

Fork is all-or-nothing: if any child fails to come up, every child started so far is rolled back and the call returns an error. On success, returns 201:

{ "sandboxes": [ <sandbox>, <sandbox>, ... ] }

Each child is a fully independent sandbox (its own ID, network, and — thanks to clone-safety — its own fresh RNG state and machine identifiers). Errors: 400 (bad count or invalid config), 404 (unknown snapshot), 500.

Example session

# create
SBX=$(curl -s -XPOST localhost:7878/sandboxes -d '{"memory_mib":1024}' | jq -r .id)

# run setup
curl -s -XPOST localhost:7878/sandboxes/$SBX/exec \
  -d '{"cmd":["sh","-lc","git clone https://github.com/x/y /app && cd /app && pip install -r requirements.txt"]}' --output -

# snapshot after setup
SNP=$(curl -s -XPOST localhost:7878/sandboxes/$SBX/snapshot | jq -r .id)

# fork 4 children from the warm snapshot
curl -s -XPOST "localhost:7878/snapshots/$SNP/fork?count=4" | jq '.sandboxes[].id'

The exec response is a binary frame stream — specified language-neutrally in wire.md, with conformance fixtures under sdks/fixtures (see sdk/wire for the reference reader/writer). The Python SDK on the roadmap wraps all of this.