# crucible

> Sandbox runtime for AI coding agents. Firecracker microVMs, a single Go binary, snapshot/fork as first-class primitives.

## Pages

- [crucible](https://cruciblehq.dev/docs)
- [HTTP API](https://cruciblehq.dev/docs/api): Base URL, authentication, error conventions, and a complete example session. The endpoint-by-endpoint contract lives in the generated API reference.
- [Create a sandbox](https://cruciblehq.dev/docs/api/create-sandbox): POST /sandboxes field by field: sizing, profiles vs images, port publishing, disk growth, and the network policy rules.
- [Exec and the stream protocol](https://cruciblehq.dev/docs/api/exec): POST /sandboxes/{id}/exec: run a command and stream framed stdout/stderr, go interactive with ?stdin=1, or use the WebSocket transport from non-Go clients.
- [File transfer](https://cruciblehq.dev/docs/api/files): Push a tar stream into the guest or read one file's bytes out: the two file endpoints behind crucible cp and the MCP file tools.
- [Fork](https://cruciblehq.dev/docs/api/fork): POST /snapshots/{id}/fork: fan out N independent sandboxes from one snapshot, all-or-nothing, with optional port publishing on a single fork.
- [Apps](https://cruciblehq.dev/docs/apps): Durable, self-healing workloads: a named spec the daemon keeps a healthy instance of, health checks, restart policies, and recovery after a daemon restart.
- [Architecture](https://cruciblehq.dev/docs/architecture): How crucible is put together, for people reading or contributing to the code: the daemon, jailer, agent, and the boundaries between them.
- [Volume backups](https://cruciblehq.dev/docs/backups): Point-in-time, consistent backups of a volume, restorable to a new volume. Back up a detached, slept, or live (fsfreeze) volume; clone a volume; keep backups on your own storage.
- [Benchmarks](https://cruciblehq.dev/docs/benchmarks): Reproducible latency measurements from crucible-bench, driving a real daemon through the same typed Go client the CLI and TUI use.
- [Changelog](https://cruciblehq.dev/docs/changelog): What shipped in each crucible release.
- [CLI overview](https://cruciblehq.dev/docs/cli): How the crucible client finds the daemon, how output composes in shell, and where every command lives.
- [App commands](https://cruciblehq.dev/docs/cli/apps): The app command family: create and update durable apps, watch their health, read their logs, and exec into the current instance.
- [Daemon, tokens, and agents](https://cruciblehq.dev/docs/cli/daemon): Run the server, manage bearer keys with daemon token, author scoped policies, and expose crucible to MCP agents.
- [Sandbox lifecycle](https://cruciblehq.dev/docs/cli/lifecycle): Stop a workload without losing the box, tear one down, open a live shell, and copy files in: stop, rm, shell, and cp.
- [Registry commands](https://cruciblehq.dev/docs/cli/registry): The registry command family: store, list, and remove the credentials the daemon uses to pull private images.
- [Run and build](https://cruciblehq.dev/docs/cli/run): crucible run in its two shapes (boot an image, or run one command and vanish) and crucible build, the local Dockerfile-to-store shortcut.
- [Sandboxes and profiles](https://cruciblehq.dev/docs/cli/sandboxes): The sandbox command family (create, ls, inspect, exec, rm) and profile ls, the daemon's rootfs catalog.
- [Snapshots and fork](https://cruciblehq.dev/docs/cli/snapshots): Freeze a warm sandbox with snapshot, then fork N independent copies of it in milliseconds: the workflow crucible is built around.
- [The network model](https://cruciblehq.dev/docs/concepts/network-model): How default-deny egress is actually enforced: one DNS proxy, one nftables table, a /30 per sandbox, and DNS-attested IPs. The concrete design, including its failure modes and non-goals.
- [Volume encryption](https://cruciblehq.dev/docs/encryption): Encryption at rest for persistent volumes: each volume is its own LUKS container with its own key, so its data can be crypto-shredded by destroying that one key.
- [Snapshot & fork](https://cruciblehq.dev/docs/fork): Freeze a running server, then fork it into independent copies that diverge without touching each other — crucible's core primitive, in one take.
- [Install](https://cruciblehq.dev/docs/install): Install crucible with one command: the Linux daemon (systemd service) or the cross-platform client (macOS / Windows / Linux) that drives a remote daemon.
- [MCP](https://cruciblehq.dev/docs/mcp): Expose crucible to any MCP-compatible agent as native tools (create, exec, snapshot, fork, apps), with operator guardrails bounding what the agent may do.
- [Networking](https://cruciblehq.dev/docs/network): Sandboxes get no network unless you say so. Enable egress with a hostname allowlist, widen it with public CIDRs or full egress, and rely on one invariant: public unicast only.
- [Observability](https://cruciblehq.dev/docs/observability): Per-app metrics on Prometheus /metrics, a reference Grafana dashboard, and (coming) OTLP export — crucible emits open standards and delegates routing to your collector.
- [Scoped tokens and policies](https://cruciblehq.dev/docs/policy): Bind an API key to a policy the daemon enforces on every request: a small, bounded, revocable capability for agents and CI.
- [Rootfs profiles](https://cruciblehq.dev/docs/profiles): Pre-baked guest rootfs images a sandbox can boot from (base, python-3.12, node-22), how they are built, and how the daemon discovers them.
- [Ingress proxy](https://cruciblehq.dev/docs/proxy): One daemon-owned listener that routes requests to many apps by name: the front door when one host runs more than one app.
- [Private registries](https://cruciblehq.dev/docs/registry): Pull private/authenticated images: store per-registry credentials on the daemon so run, app create, and app self-heal can pull them.
- [Roadmap](https://cruciblehq.dev/docs/roadmap): What has shipped and what is planned, in rough order, grouped into coherent milestones.
- [Go SDK](https://cruciblehq.dev/docs/sdks/go): The official Go client: a zero-dependency module, versioned independently of the daemon, covering the full API including the exec stream.
- [SDKs](https://cruciblehq.dev/docs/sdks/overview): Drive crucible from your own code: boot sandboxes, stream exec output, push files, snapshot and fork. Where each language client stands.
- [Python SDK](https://cruciblehq.dev/docs/sdks/python): Help wanted: no Python client exists yet, and it is a deliberately well-prepared contribution with the hard parts already specified and fixtured.
- [TypeScript SDK](https://cruciblehq.dev/docs/sdks/typescript): A typed, zero-runtime-dependency fetch client with streaming exec and a frame codec verified against the shared conformance fixtures.
- [Secrets](https://cruciblehq.dev/docs/secrets): Encrypted secret bundles: store sensitive config once, inject it into an app's environment — without the value ever touching the app spec, backups, or logs.
- [Serverless (wake-on-TCP)](https://cruciblehq.dev/docs/serverless): Scale-to-zero for any TCP service: databases, caches, queues, pub/sub. A published port wakes its app on the first connection; it sleeps when idle. Run a serverless postgres or redis that costs zero RAM until someone connects.
- [TLS & custom domains](https://cruciblehq.dev/docs/tls): Automatic HTTPS for apps: the ingress proxy terminates TLS with a managed certificate, issues and renews it over ACME, and routes both generated and custom domains.
- [TUI](https://cruciblehq.dev/docs/tui): A live terminal dashboard for driving and observing a daemon: running sandboxes, the fork tree, and streaming exec, with no daemon-side state of its own.
- [Upgrading the daemon without losing your apps](https://cruciblehq.dev/docs/upgrades)
- [Vision](https://cruciblehq.dev/docs/vision): What crucible is for and why it is shaped this way: the stable motivation and principles behind the runtime.
- [Persistent volumes](https://cruciblehq.dev/docs/volumes): Durable block-device volumes that outlive a sandbox or app — data that survives destroy/re-create, hard kills, redeploys, sleep, and daemon restarts.
- [Wire protocol](https://cruciblehq.dev/docs/wire): The parts of crucible's API OpenAPI cannot express, specified language-neutrally for SDK authors: the exec frame stream and its conformance fixtures.
- [List apps](https://cruciblehq.dev/docs/api-reference/listapps)
- [Create a durable app](https://cruciblehq.dev/docs/api-reference/createapp): Creates a named app the daemon keeps a healthy instance of, re-creating it from spec after a daemon restart.
- [Get an app](https://cruciblehq.dev/docs/api-reference/getapp): Desired state plus observed status (instance id, phase, health, restarts).
- [Update an app](https://cruciblehq.dev/docs/api-reference/updateapp): Replaces the app's spec (name immutable), diff-aware: a change to an instance-defining field (image, cpu/memory, volumes, env, entrypoint, ...) bumps the generation and redeploys the instance, while a...
- [Delete an app](https://cruciblehq.dev/docs/api-reference/deleteapp): Removes the app and tears down its instance on the next reconcile.
- [List an app's custom domains](https://cruciblehq.dev/docs/api-reference/listappdomains): The custom domains (FQDNs) attached to the app; the ingress proxy routes them and, in terminate mode, obtains a certificate for each.
- [Attach a custom domain to an app](https://cruciblehq.dev/docs/api-reference/addappdomain): Attaches a custom domain (FQDN, globally unique — one domain to one app).
- [Detach a custom domain](https://cruciblehq.dev/docs/api-reference/removeappdomain): Detaches a custom domain from the app (idempotent).
- [Interactive exec into an app (WebSocket)](https://cruciblehq.dev/docs/api-reference/appexecws): WebSocket interactive exec against the app's current instance; identical contract to GET /sandboxes/{id}/exec.
- [Run a command in an app's current instance (streams frames)](https://cruciblehq.dev/docs/api-reference/appexec): Resolves the app to its current instance and runs the command there, streaming the same length-prefixed frame protocol as POST /sandboxes/{id}/exec (?stdin=1 for a hijacked interactive session).
- [Read an app's current-instance logs](https://cruciblehq.dev/docs/api-reference/applogs): Durable logs (service output + exec activity) of the app's current instance; same shape as GET /sandboxes/{id}/logs.
- [Get an app's usage metrics](https://cruciblehq.dev/docs/api-reference/appusage): One live app's persistent usage metrics, accrued to now.
- [List all volume backups](https://cruciblehq.dev/docs/api-reference/listbackups)
- [Delete a backup](https://cruciblehq.dev/docs/api-reference/deletebackup)
- [List app lifecycle events](https://cruciblehq.dev/docs/api-reference/listevents): A batch of app lifecycle events (created / phase_changed / health_changed / domain / deleted) after the given cursor, plus the current max cursor.
- [Liveness check](https://cruciblehq.dev/docs/api-reference/health): Always returns 200 and is exempt from auth, so probes work without a key.
- [List cached images](https://cruciblehq.dev/docs/api-reference/listimages)
- [Pull and convert an OCI image](https://cruciblehq.dev/docs/api-reference/pullimage): Experimental.
- [Import a docker-save archive](https://cruciblehq.dev/docs/api-reference/importimage): Experimental.
- [Get a cached image](https://cruciblehq.dev/docs/api-reference/getimage)
- [Delete a cached image](https://cruciblehq.dev/docs/api-reference/deleteimage)
- [List rootfs profiles](https://cruciblehq.dev/docs/api-reference/listprofiles): The rootfs profiles the daemon can boot sandboxes from.
- [List registry credentials](https://cruciblehq.dev/docs/api-reference/listregistrycredentials): Lists stored registry credentials as host + username only — never the secret.
- [Store a private-registry credential](https://cruciblehq.dev/docs/api-reference/registrylogin): Adds or replaces the credential used to pull from a private registry (`crucible registry login`).
- [Remove a registry credential](https://cruciblehq.dev/docs/api-reference/registrylogout): Deletes the stored credential for a registry host (`crucible registry logout`).
- [List sandboxes](https://cruciblehq.dev/docs/api-reference/listsandboxes)
- [Get a sandbox](https://cruciblehq.dev/docs/api-reference/getsandbox)
- [Destroy a sandbox](https://cruciblehq.dev/docs/api-reference/deletesandbox)
- [Interactive exec (WebSocket)](https://cruciblehq.dev/docs/api-reference/execsandboxws): WebSocket upgrade for a full-duplex interactive exec.
- [Read a single guest file](https://cruciblehq.dev/docs/api-reference/getfile): Returns the raw bytes of one guest file (?path), capped at ?max_bytes.
- [Read durable sandbox logs](https://cruciblehq.dev/docs/api-reference/sandboxlogs): Durable per-sandbox logs (service output + exec activity) that survive the sandbox.
- [Service status](https://cruciblehq.dev/docs/api-reference/servicestatus)
- [Configure the supervised service](https://cruciblehq.dev/docs/api-reference/configureservice): Experimental.
- [Stream service logs](https://cruciblehq.dev/docs/api-reference/servicelogs): Experimental.
- [Restart the service](https://cruciblehq.dev/docs/api-reference/restartservice)
- [Start the service](https://cruciblehq.dev/docs/api-reference/startservice)
- [Stop the service](https://cruciblehq.dev/docs/api-reference/stopservice)
- [Snapshot a sandbox](https://cruciblehq.dev/docs/api-reference/createsnapshot)
- [List secret bundles](https://cruciblehq.dev/docs/api-reference/listsecrets): The names of stored secret bundles — never their contents.
- [List a bundle's key names](https://cruciblehq.dev/docs/api-reference/getsecretkeys): One bundle's key NAMES — never the values.
- [Store a secret bundle](https://cruciblehq.dev/docs/api-reference/putsecret): Stores or replaces an encrypted secret bundle (a set of key→value pairs).
- [Delete a secret bundle](https://cruciblehq.dev/docs/api-reference/deletesecret): Removes a secret bundle (idempotent).
- [List snapshots](https://cruciblehq.dev/docs/api-reference/listsnapshots)
- [Get a snapshot](https://cruciblehq.dev/docs/api-reference/getsnapshot)
- [Delete a snapshot](https://cruciblehq.dev/docs/api-reference/deletesnapshot)
- [List every app's usage metrics](https://cruciblehq.dev/docs/api-reference/listusage): Persistent usage metrics: durable, cumulative per-app counters (compute, memory, requests, storage) that survive a daemon restart, including retained records for deleted apps.
- [List volumes](https://cruciblehq.dev/docs/api-reference/listvolumes)
- [Create a persistent volume](https://cruciblehq.dev/docs/api-reference/createvolume): Creates a durable block-device volume (formatted ext4 on first use).
- [Reload the encryption keyring](https://cruciblehq.dev/docs/api-reference/reloadvolumekeys): Re-reads the daemon's key sources and swaps the keyring in without a restart.
- [Re-wrap every volume off a key](https://cruciblehq.dev/docs/api-reference/rewrapvolumes): Re-wraps every volume currently on from_key_id to to_key_id — rotate a key off so it can be retired.
- [Get a volume](https://cruciblehq.dev/docs/api-reference/getvolume)
- [Delete a volume](https://cruciblehq.dev/docs/api-reference/deletevolume): Deletes the volume and its data.
- [List a volume's backups](https://cruciblehq.dev/docs/api-reference/listvolumebackups)
- [Back up a volume](https://cruciblehq.dev/docs/api-reference/backupvolume): Takes a consistent point-in-time backup of the volume, restorable to a new volume.
- [Clone a volume](https://cruciblehq.dev/docs/api-reference/clonevolume): Copies the quiescent volume {name} into a new volume.
- [Grow a volume](https://cruciblehq.dev/docs/api-reference/growvolume): Enlarges a detached volume's backing store and ext4 filesystem to size_bytes (grow-only; a value at or below the current size is rejected).
- [Restore a backup to a new volume](https://cruciblehq.dev/docs/api-reference/restorevolume): Materialises a backup into the new volume {name}.
- [Re-wrap a volume's encryption key](https://cruciblehq.dev/docs/api-reference/rewrapvolume): Re-wraps the volume's per-volume key under a different keyring key (rotation; no data is re-encrypted, safe on a live volume).
- [Crypto-shred an encrypted volume](https://cruciblehq.dev/docs/api-reference/shredvolume): Destroys the volume's keyslots and deletes its wrapped key, making the data permanently unrecoverable.
- [Effective policy for the caller](https://cruciblehq.dev/docs/api-reference/whoami): Reports whether the token is scoped and, if so, the policy the daemon enforces for it.
- [crucible](https://cruciblehq.dev/docs/api-reference)

## API reference

- [GET /apps](https://cruciblehq.dev/docs/api-reference#listApps): List apps
- [POST /apps](https://cruciblehq.dev/docs/api-reference#createApp): Create a durable app
- [GET /apps/{name}](https://cruciblehq.dev/docs/api-reference#getApp): Get an app
- [PUT /apps/{name}](https://cruciblehq.dev/docs/api-reference#updateApp): Update an app
- [DELETE /apps/{name}](https://cruciblehq.dev/docs/api-reference#deleteApp): Delete an app
- [GET /apps/{name}/domains](https://cruciblehq.dev/docs/api-reference#listAppDomains): List an app's custom domains
- [POST /apps/{name}/domains](https://cruciblehq.dev/docs/api-reference#addAppDomain): Attach a custom domain to an app
- [DELETE /apps/{name}/domains/{domain}](https://cruciblehq.dev/docs/api-reference#removeAppDomain): Detach a custom domain
- [GET /apps/{name}/exec](https://cruciblehq.dev/docs/api-reference#appExecWS): Interactive exec into an app (WebSocket)
- [POST /apps/{name}/exec](https://cruciblehq.dev/docs/api-reference#appExec): Run a command in an app's current instance (streams frames)
- [GET /apps/{name}/logs](https://cruciblehq.dev/docs/api-reference#appLogs): Read an app's current-instance logs
- [GET /apps/{name}/usage](https://cruciblehq.dev/docs/api-reference#appUsage): Get an app's usage metrics
- [GET /backups](https://cruciblehq.dev/docs/api-reference#listBackups): List all volume backups
- [DELETE /backups/{id}](https://cruciblehq.dev/docs/api-reference#deleteBackup): Delete a backup
- [GET /events](https://cruciblehq.dev/docs/api-reference#listEvents): List app lifecycle events
- [GET /healthz](https://cruciblehq.dev/docs/api-reference#health): Liveness check
- [GET /images](https://cruciblehq.dev/docs/api-reference#listImages): List cached images
- [POST /images](https://cruciblehq.dev/docs/api-reference#pullImage): Pull and convert an OCI image
- [POST /images/import](https://cruciblehq.dev/docs/api-reference#importImage): Import a docker-save archive
- [GET /images/{ref}](https://cruciblehq.dev/docs/api-reference#getImage): Get a cached image
- [DELETE /images/{ref}](https://cruciblehq.dev/docs/api-reference#deleteImage): Delete a cached image
- [GET /profiles](https://cruciblehq.dev/docs/api-reference#listProfiles): List rootfs profiles
- [GET /registry/credentials](https://cruciblehq.dev/docs/api-reference#listRegistryCredentials): List registry credentials
- [POST /registry/credentials](https://cruciblehq.dev/docs/api-reference#registryLogin): Store a private-registry credential
- [DELETE /registry/credentials/{host}](https://cruciblehq.dev/docs/api-reference#registryLogout): Remove a registry credential
- [GET /sandboxes](https://cruciblehq.dev/docs/api-reference#listSandboxes): List sandboxes
- [POST /sandboxes](https://cruciblehq.dev/docs/api-reference#createSandbox): Create a sandbox
- [GET /sandboxes/{id}](https://cruciblehq.dev/docs/api-reference#getSandbox): Get a sandbox
- [DELETE /sandboxes/{id}](https://cruciblehq.dev/docs/api-reference#deleteSandbox): Destroy a sandbox
- [GET /sandboxes/{id}/exec](https://cruciblehq.dev/docs/api-reference#execSandboxWS): Interactive exec (WebSocket)
- [POST /sandboxes/{id}/exec](https://cruciblehq.dev/docs/api-reference#execSandbox): Run a command (streams frames)
- [GET /sandboxes/{id}/files](https://cruciblehq.dev/docs/api-reference#getFile): Read a single guest file
- [POST /sandboxes/{id}/files](https://cruciblehq.dev/docs/api-reference#putFiles): Push files into a sandbox
- [GET /sandboxes/{id}/logs](https://cruciblehq.dev/docs/api-reference#sandboxLogs): Read durable sandbox logs
- [GET /sandboxes/{id}/service](https://cruciblehq.dev/docs/api-reference#serviceStatus): Service status
- [PUT /sandboxes/{id}/service](https://cruciblehq.dev/docs/api-reference#configureService): Configure the supervised service
- [GET /sandboxes/{id}/service/logs](https://cruciblehq.dev/docs/api-reference#serviceLogs): Stream service logs
- [POST /sandboxes/{id}/service/restart](https://cruciblehq.dev/docs/api-reference#restartService): Restart the service
- [POST /sandboxes/{id}/service/start](https://cruciblehq.dev/docs/api-reference#startService): Start the service
- [POST /sandboxes/{id}/service/stop](https://cruciblehq.dev/docs/api-reference#stopService): Stop the service
- [POST /sandboxes/{id}/snapshot](https://cruciblehq.dev/docs/api-reference#createSnapshot): Snapshot a sandbox
- [GET /secrets](https://cruciblehq.dev/docs/api-reference#listSecrets): List secret bundles
- [GET /secrets/{name}](https://cruciblehq.dev/docs/api-reference#getSecretKeys): List a bundle's key names
- [PUT /secrets/{name}](https://cruciblehq.dev/docs/api-reference#putSecret): Store a secret bundle
- [DELETE /secrets/{name}](https://cruciblehq.dev/docs/api-reference#deleteSecret): Delete a secret bundle
- [GET /snapshots](https://cruciblehq.dev/docs/api-reference#listSnapshots): List snapshots
- [GET /snapshots/{id}](https://cruciblehq.dev/docs/api-reference#getSnapshot): Get a snapshot
- [DELETE /snapshots/{id}](https://cruciblehq.dev/docs/api-reference#deleteSnapshot): Delete a snapshot
- [POST /snapshots/{id}/fork](https://cruciblehq.dev/docs/api-reference#forkSnapshot): Fork sandboxes from a snapshot
- [GET /usage](https://cruciblehq.dev/docs/api-reference#listUsage): List every app's usage metrics
- [GET /volumes](https://cruciblehq.dev/docs/api-reference#listVolumes): List volumes
- [POST /volumes](https://cruciblehq.dev/docs/api-reference#createVolume): Create a persistent volume
- [POST /volumes/keys/reload](https://cruciblehq.dev/docs/api-reference#reloadVolumeKeys): Reload the encryption keyring
- [POST /volumes/rewrap](https://cruciblehq.dev/docs/api-reference#rewrapVolumes): Re-wrap every volume off a key
- [GET /volumes/{name}](https://cruciblehq.dev/docs/api-reference#getVolume): Get a volume
- [DELETE /volumes/{name}](https://cruciblehq.dev/docs/api-reference#deleteVolume): Delete a volume
- [GET /volumes/{name}/backups](https://cruciblehq.dev/docs/api-reference#listVolumeBackups): List a volume's backups
- [POST /volumes/{name}/backups](https://cruciblehq.dev/docs/api-reference#backupVolume): Back up a volume
- [POST /volumes/{name}/clone](https://cruciblehq.dev/docs/api-reference#cloneVolume): Clone a volume
- [POST /volumes/{name}/grow](https://cruciblehq.dev/docs/api-reference#growVolume): Grow a volume
- [POST /volumes/{name}/restore](https://cruciblehq.dev/docs/api-reference#restoreVolume): Restore a backup to a new volume
- [POST /volumes/{name}/rewrap](https://cruciblehq.dev/docs/api-reference#rewrapVolume): Re-wrap a volume's encryption key
- [POST /volumes/{name}/shred](https://cruciblehq.dev/docs/api-reference#shredVolume): Crypto-shred an encrypted volume
- [GET /whoami](https://cruciblehq.dev/docs/api-reference#whoami): Effective policy for the caller