Sandboxes and GPU routes

Create and manage sandboxes, their snapshots, branches and egress rules, and attach GPU leases.

Every route is on https://sandbox.tangle.tools and takes your account API key as Authorization: Bearer <key> unless it says otherwise. Errors use the shape in Error codes. This page is generated from the OpenAPI document, which also has every response schema.

Sandboxes

Create a new sandbox

POST /v1/sandboxes

Request body (application/json):

List sandboxes

GET /v1/sandboxes

Check whether the default placement pool can admit a new sandbox

GET /v1/sandboxes/admission

Run multiple tasks in parallel

POST /v1/sandboxes/batch/run

Without Idempotency-Key, disconnecting stops the batch. With a key, the exact-body run continues and later matching requests join or replay it. Persistent reuseKey selects stable workspaces independently.

Request body (application/json): one of 2 shapes; see the OpenAPI document.

Delete every sandbox whose metadata matches

POST /v1/sandboxes/delete-matching

Deletes the caller’s own sandboxes whose metadata values start with the given prefixes, at most 25 per call in ID order, and reports each one. When matches remain, pass next as after to attempt them. Repeating the call is safe: a confirmed-gone sandbox no longer matches. Stop creating matching sandboxes before calling, and call again once in-flight creates have settled: complete covers only the sandboxes this call listed.

Request body (application/json):

List the sandbox compute generations created for a caller run

GET /v1/sandboxes/runs/{run}

Get the ID of the calling sandbox

GET /v1/sandboxes/self/identity

Needs a credential bound to one sandbox. An account API key gets 403: select the sandbox by ID instead. The response is not cached.

Get sandbox details

GET /v1/sandboxes/{id}

Delete a sandbox

DELETE /v1/sandboxes/{id}

Deletes the sandbox. A sandbox with live branch children is refused (409 CHILDREN_EXIST) unless cascade=true, which deletes the whole lineage children-first. Platform-managed snapshot repositories are reclaimed after the deleted-retention window for internal accounts only; customer repositories remain until explicitly deleted by their owner. Preservation holds and active exports/restores are honored. With wait=false it may instead answer 202 as soon as the delete is durably accepted: poll operation.statusUrl (or Location) until the operation is succeeded (with result.deleted) or failed. The runtime runs and bills until the delete kills it. An Idempotency-Key names the delete for a retry whose 202 was lost. With until=removed, that status URL keeps polling through physical reclaim. Cascades keep the synchronous answer; a 200 means the delete finished.

Branch a running sandbox into copy-on-write children

POST /v1/sandboxes/{id}/branch

Forks a RUNNING sandbox’s live memory into count copy-on-write children that share the parent’s pages at branch time (Firecracker UFFD copy-on-write). The parent stays running. Fails loud when the active driver cannot branch live memory; it never degrades to fresh, empty sandboxes.

Request body (application/json):

Get sandbox driver info

GET /v1/sandboxes/{id}/driver

Update sandbox egress policy

PATCH /v1/sandboxes/{id}/egress

Update the egress (outbound network) policy for a running sandbox. The proxy is restarted with the new policy (~2-5s downtime).

Request body (application/json):

List the hosts a sandbox reached

GET /v1/sandboxes/{id}/egress/activity

Every destination this sandbox’s egress proxy allowed or refused in the inspected window, and whether that observation can be trusted. This is the OPPOSITE question to /egress/denials, and unlike that route it is deliberately not best-effort: it exists to support the negative claim ‘this sandbox reached nothing’, which an empty list cannot carry on its own. destinations: [] with complete: true is evidence; destinations: [] with complete: false is an absence of evidence, and incompleteReasons names what was missing. A hop that could not reach the host reports hop-unreachable rather than an empty list, so an unreadable path can never be read as a clean sandbox.

List recent egress denials

GET /v1/sandboxes/{id}/egress/denials

Destinations this sandbox tried to reach that its egress policy refused, newest first. The sandbox’s 403 body names each refusal’s host and policy (the same pair as rejectedBy); this keeps the history. Best-effort: an empty list means either nothing was refused or the proxy is no longer readable.

Get a sandbox’s egress for a calendar month

GET /v1/sandboxes/{id}/egress/usage

Bytes this sandbox sent in one calendar month (UTC), the account’s allowance it shares (2 TB per account per month on paid plans, 100 GiB on Free), the account’s total and overage, and the USD the meter charged or reserved for this sandbox’s captures.

Read caller credential recovery policy

GET /v1/sandboxes/{id}/env-recovery

Replace or dry-run a stopped sandbox’s caller resupply policy

PUT /v1/sandboxes/{id}/env-recovery

Request body (application/json):

Subscribe to sandbox events (SSE)

GET /v1/sandboxes/{id}/events

Publish the sandbox workspace as an image

POST /v1/sandboxes/{id}/images

Builds the Dockerfile in the sandbox workspace and pushes the image to the registry named in repository, with the credentials in auth. The sandbox must be running, and filesystemIncarnationId must be the value its details report. The request can take up to 15 minutes. Send an Idempotency-Key to make a retry safe; reusing a key with different inputs fails with IDEMPOTENCY_KEY_REUSED. A key is generated when you omit one, and the response returns it.

Request body (application/json):

Get an MCP endpoint for this sandbox

GET /v1/sandboxes/{id}/mcp

Returns a paste-able MCP host config (Claude Desktop, Cursor, claude-code, codex, …) plus a freshly-minted, capability-scoped JWT. The token is short-lived and can ONLY call MCP routes; it cannot reach admin endpoints (/exec, /files, …) on the sandbox. Call again to rotate.

?capabilities=computer_use is also the mint route for desktop control: the resulting token is what POST /computer-use/action, /a11y, and /mcp require. POST /v1/sandboxes/{id}/scoped-token cannot grant it; that route covers session reads, files, and terminals only.

Install a native CLI credential in a sandbox

POST /v1/sandboxes/{id}/native-credentials

Names a stored secret; no secret value is sent or returned. claude-code takes a token reference, codex a bundle or files reference. Needs write access to the sandbox, and a personal sandbox must be owned by the caller. Isolated sandboxes are refused. The grant is recorded as a sandbox.native_credential.grant audit event.

Request body (application/json):

Get an accepted stop, snapshot or delete

GET /v1/sandboxes/{id}/operations/{operationId}

Reports an operation a wait=false stop, snapshot or delete accepted. Poll until state is succeeded or failed. Still readable after the sandbox is deleted: a delete is authorized from the scope it was accepted under (its owner, or a current member of its team). Unknown ids and ids of other tenants answer the same 404. waitMs holds the read while it runs; a delete holds 10 s.

Read verified HIPAA placement evidence

GET /v1/sandboxes/{id}/placement-attestation

Rebuild a stopped sandbox runtime

POST /v1/sandboxes/{id}/rebuild

Requires a stopped sandbox. Confirms a durable snapshot, then creates a new runtime under the same sandbox ID. The optional env body resupplies public values that are not stored at rest. A refused rebuild keeps the stopped runtime.

Resume a stopped sandbox

POST /v1/sandboxes/{id}/resume

Resumes a stopped sandbox. A sandbox that is already running answers 200 with its current state. The optional JSON body { "env": { "KEY": "value" } } resupplies public env values that are not stored at rest, such as a per-run coordination token or a secret passed at create. A resume that must build a new runtime without them answers 409 RESUME_ENV_REQUIRED with missingEnvKeys. The values are used only when the resume builds a new runtime.

Fork a running agent sandbox N ways and run the same turn in each

POST /v1/sandboxes/{id}/rollouts

Speculative rollouts: branches the RUNNING sandbox into n copy-on-write children, sends the same message parts to a fresh agent session in every child in parallel, and (optionally) scores each child by running scorer.command inside it; exit 0 passes and stdout is parsed as the numeric score. Responds once the children exist; poll GET /v1/sandboxes/{id}/rollouts/{rolloutId} for turn results, per-child errors, and the winner. Children are KEPT for the caller to promote or delete: they are first-class sandboxes that live independently of the parent (deleting the parent reaps only the shared branch-base snapshots once the children are gone; a parent with live children refuses delete without cascade=true).

Request body (application/json):

Poll a rollout’s status and scored per-child results

GET /v1/sandboxes/{id}/rollouts/{rolloutId}

Failed or timed-out children appear as result entries with error set and no score; partial results are never dropped. winner is the child with the highest numeric score (command scorer only).

Send a GET request to the sandbox runtime

GET /v1/sandboxes/{id}/runtime/{path}

Forwards the request to the sandbox runtime at the same sub-path and relays its status, headers and body. Accepts an account API key or a scoped sandbox token from POST /v1/sandboxes/{id}/scoped-token. Needs read access to the sandbox. A GET with Upgrade: websocket to terminals/{connectionId}/ws or ssh opens a WebSocket and answers 101; a scoped token can open only the terminal socket. A request that starts paid compute, such as an agent run or exec, is refused with 402 or 429 while the paying account has debt or is below the balance floor, and it resumes a suspended sandbox first. Runtime error bodies are returned in the standard error shape.

Send a HEAD request to the sandbox runtime

HEAD /v1/sandboxes/{id}/runtime/{path}

Forwards the request to the sandbox runtime at the same sub-path and relays its status, headers and body. Accepts an account API key or a scoped sandbox token from POST /v1/sandboxes/{id}/scoped-token. Needs read access to the sandbox. A request that starts paid compute, such as an agent run or exec, is refused with 402 or 429 while the paying account has debt or is below the balance floor, and it resumes a suspended sandbox first. Runtime error bodies are returned in the standard error shape.

Send a POST request to the sandbox runtime

POST /v1/sandboxes/{id}/runtime/{path}

Forwards the request to the sandbox runtime at the same sub-path and relays its status, headers and body. Accepts an account API key or a scoped sandbox token from POST /v1/sandboxes/{id}/scoped-token. Needs write access to the sandbox. POST agents/run answers when the run finishes, with { success: true, data } or { success: false, error } under the run’s status. POST agents/run/stream answers with an event stream. A request that starts paid compute, such as an agent run or exec, is refused with 402 or 429 while the paying account has debt or is below the balance floor, and it resumes a suspended sandbox first. Runtime error bodies are returned in the standard error shape.

Request body: application/json.

Send a PUT request to the sandbox runtime

PUT /v1/sandboxes/{id}/runtime/{path}

Forwards the request to the sandbox runtime at the same sub-path and relays its status, headers and body. Accepts an account API key or a scoped sandbox token from POST /v1/sandboxes/{id}/scoped-token. Needs write access to the sandbox. A request that starts paid compute, such as an agent run or exec, is refused with 402 or 429 while the paying account has debt or is below the balance floor, and it resumes a suspended sandbox first. Runtime error bodies are returned in the standard error shape.

Request body: application/json.

Send a PATCH request to the sandbox runtime

PATCH /v1/sandboxes/{id}/runtime/{path}

Forwards the request to the sandbox runtime at the same sub-path and relays its status, headers and body. Accepts an account API key or a scoped sandbox token from POST /v1/sandboxes/{id}/scoped-token. Needs write access to the sandbox. A request that starts paid compute, such as an agent run or exec, is refused with 402 or 429 while the paying account has debt or is below the balance floor, and it resumes a suspended sandbox first. Runtime error bodies are returned in the standard error shape.

Request body: application/json.

Send a DELETE request to the sandbox runtime

DELETE /v1/sandboxes/{id}/runtime/{path}

Forwards the request to the sandbox runtime at the same sub-path and relays its status, headers and body. Accepts an account API key or a scoped sandbox token from POST /v1/sandboxes/{id}/scoped-token. Needs write access to the sandbox. A request that starts paid compute, such as an agent run or exec, is refused with 402 or 429 while the paying account has debt or is below the balance floor, and it resumes a suspended sandbox first. Runtime error bodies are returned in the standard error shape.

Request body: application/json.

Mint a scoped consumer-side token for direct sandbox access

POST /v1/sandboxes/{id}/scoped-token

Session/project tokens read SessionGateway streams. Runtime tokens grant session-runtime: read + workspace + terminal, or read-only: sandbox-wide read. Set access: read-only on session-runtime for session-bound read alone; the response must echo that restriction. Runtime read includes screenshots; workspace adds file writes and terminal adds its WebSocket. No scope here grants desktop input, /a11y or /mcp: mint computer_use separately at GET /v1/sandboxes/{id}/mcp?capabilities=computer_use. Missing-capability 403 responses identify the required capability and its mint route.

Request body (application/json): one of 3 shapes; see the OpenAPI document.

Create a snapshot of sandbox state

POST /v1/sandboxes/{id}/snapshot

Request body (application/json):

Create a snapshot of sandbox state

POST /v1/sandboxes/{id}/snapshots

Answers 202 once capture is durably accepted. Poll operation.statusUrl until succeeded or failed; a successful result names the snapshot. Writes made before the request are included. Wait for completion before writing data that must remain outside the snapshot.

Request body (application/json):

List snapshots for a sandbox

GET /v1/sandboxes/{id}/snapshots

For a deleted sandbox whose final snapshot is retained, its owner gets that snapshot alone, marked final, with deleted: true. Anyone else, a team member included, gets 404, as for a sandbox with no retained snapshot.

Get sandbox snapshot restore job status

GET /v1/sandboxes/{id}/snapshots/jobs/{jobId}

Delete a sandbox snapshot

DELETE /v1/sandboxes/{id}/snapshots/{snapshotId}

Restore a sandbox from a snapshot

POST /v1/sandboxes/{id}/snapshots/{snapshotId}/restore

Restores the whole workspace from the snapshot. The optional JSON body { "paths": ["relative/path"] } restores only those workspace-relative paths and leaves every other file untouched; an empty body restores the whole workspace. A body that is present but is not that JSON object answers 400, and nothing is restored. With waitMs the 202 is held until the job finishes and carries its status, so the caller needs no poll. A repeat under the same Idempotency-Key answers the same job for an hour after it ends; the same key with another snapshot or paths is another restore.

Stop a sandbox (keeps state)

POST /v1/sandboxes/{id}/stop

Answers once the sandbox is stopped and its final workspace generation is durable. With wait=false it may instead answer 202 as soon as the stop is durably accepted: poll operation.statusUrl (or Location) until the operation is succeeded or failed. Billing runs until the runtime is actually stopped, and a resume issued meanwhile waits for the stop. A 200 to a wait=false request means the stop already finished synchronously. A synchronous stop accepts { "retain": { "paths": ["relative/path"] } } to export its exact remotely confirmed stopped workspace before answering.

Export sandbox trace and intelligence envelope

GET /v1/sandboxes/{id}/trace

Look up an idempotent workspace operation

POST /v1/sandboxes/{id}/workspace-operations/lookup

Request body (application/json):

List sandbox shape presets and the caller’s ceiling

GET /v1/shapes

Returns the named sandbox sizes, which one is the platform’s default, and the largest shape this account can be granted on this deployment. Presets are the platform’s numbers and are not clamped per account: a preset above ceiling (the default small on a plan whose ceiling sits below it) is granted clamped to the ceiling when the create names no size or marks the size advisory, and refused with RESOURCES_EXCEED_LIMIT when the create names that preset’s numbers explicitly. default names the platform’s default preset: a create that sends no resources receives that preset’s CPU and memory, but its disk is currently held at 2 GiB (the host warm-seed quota) rather than the preset’s, so name resources.diskGB when you need more.

GPU

List GPU leases

GET /v1/sandboxes/{id}/gpu/leases

Needs read access to the sandbox. Each lease’s endpointUrl is its serving URL on this API. A destroyed lease in the list has its final charge recorded once.

Attach a GPU lease

POST /v1/sandboxes/{id}/gpu/leases

Needs admin access to the sandbox and a paid seat or funded balance. The plan’s accelerator limit applies per sandbox. maxSpendUsd and maxLifetimeSeconds end the lease when reached.

Request body (application/json):

Renew a GPU lease

PATCH /v1/sandboxes/{id}/gpu/leases/{leaseId}

Sets a new lifetime or spend cap. Send at least one of maxLifetimeSeconds and maxSpendUsd. Needs admin access to the sandbox and a paid seat or funded balance.

Request body (application/json):

Detach a GPU lease

DELETE /v1/sandboxes/{id}/gpu/leases/{leaseId}

Needs write access to the sandbox. Destroys the lease and records its final charge. The response carries the lease’s billing summary.

Send a GET request to a GPU lease endpoint

GET /v1/sandboxes/{id}/gpu/leases/{leaseId}/endpoint/{path}

Forwards the request to the lease’s HTTPS serving endpoint, with its query string, body, Content-Type and Accept. The response status, headers and body are the endpoint’s. Needs write access to the sandbox. A request in flight counts as lease activity.

Send a POST request to a GPU lease endpoint

POST /v1/sandboxes/{id}/gpu/leases/{leaseId}/endpoint/{path}

Forwards the request to the lease’s HTTPS serving endpoint, with its query string, body, Content-Type and Accept. The response status, headers and body are the endpoint’s. Needs write access to the sandbox. A request in flight counts as lease activity.

Request body: application/json.

Send a PUT request to a GPU lease endpoint

PUT /v1/sandboxes/{id}/gpu/leases/{leaseId}/endpoint/{path}

Forwards the request to the lease’s HTTPS serving endpoint, with its query string, body, Content-Type and Accept. The response status, headers and body are the endpoint’s. Needs write access to the sandbox. A request in flight counts as lease activity.

Request body: application/json.

Send a PATCH request to a GPU lease endpoint

PATCH /v1/sandboxes/{id}/gpu/leases/{leaseId}/endpoint/{path}

Forwards the request to the lease’s HTTPS serving endpoint, with its query string, body, Content-Type and Accept. The response status, headers and body are the endpoint’s. Needs write access to the sandbox. A request in flight counts as lease activity.

Request body: application/json.

Send a DELETE request to a GPU lease endpoint

DELETE /v1/sandboxes/{id}/gpu/leases/{leaseId}/endpoint/{path}

Forwards the request to the lease’s HTTPS serving endpoint, with its query string, body, Content-Type and Accept. The response status, headers and body are the endpoint’s. Needs write access to the sandbox. A request in flight counts as lease activity.

Request body: application/json.

Run a command on a GPU lease

POST /v1/sandboxes/{id}/gpu/leases/{leaseId}/exec

Needs write access to the sandbox. Runs the command on the lease’s accelerator host and answers when it exits. The call is recorded as a sandbox exec access event.

Request body (application/json):

List GPU providers

GET /v1/sandboxes/{id}/gpu/providers

Needs read access to the sandbox. Checks each provider’s credential with a fresh read-only call. Send acceleratorKind to also get each provider’s hourly price for that GPU.

Next steps

• In-sandbox runtime routes: commands, files and terminals inside a sandbox.
• Sessions and backends: coding-agent sessions and the agents you can run.
• Create, stop and delete: the same operations from the SDKs and CLI.