Sandboxes

Get a sandbox

GET
/sandboxes/{sandboxId}

Authorization

ApiKeyAuth
AGENTBOX-API-KEY<token>

In: header

Path Parameters

sandboxId*string

Sandbox identifier.

  • Single-cluster: a bare UUID v7 such as 5de15c92-8fb5-440f-a9ea-7f62f734f1b9.
  • Cross-cluster: a {clusterID}.{uuid} composite such as cluster1.5de15c92-8fb5-440f-a9ea-7f62f734f1b9 (dot-separated). The clusterID prefix tells the gateway which Worker cluster owns this sandbox; the server parses it out transparently. Discover valid cluster IDs via GET /clusters.

Because of the composite form, this field is NOT a strict RFC 4122 UUID — clients must treat it as an opaque string. Parsing reference: pkg/utils/cluster/sandbox_id.go::SplitSandboxID.

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://sandboxes/5de15c92-8fb5-440f-a9ea-7f62f734f1b9"
{  "sandbox": {    "sandboxId": "5de15c92-8fb5-440f-a9ea-7f62f734f1b9",    "namespace": "t-team1-user1",    "poolName": "my-pool",    "podName": "my-pool-xy7k2",    "status": "Running",    "claimedAt": "2026-04-21T10:15:30Z",    "team": "team1",    "user": "user1",    "endpoints": {      "default": "https://agentbox.example.com/v1/sandboxes/5de15c92-8fb5-440f-a9ea-7f62f734f1b9"    }  }}
{  "error": "invalid API key"}
{  "error": "sandbox t-team1-user1/5de15c92-8fb5-440f-a9ea-7f62f734f1b9 not found or already terminated"}
{  "error": "string",  "errorCode": "API_KEY_REQUIRED",  "detail": null}

Execute a command inside a sandbox POST

**DEPRECATED** — will be removed in a future version. Prefer opening an interactive exec session with the WebSocket endpoint (see `POST /sandboxes/{sandboxId}/exec-token` + `wss://.../terminal`) for any non-trivial command execution. This REST call is limited to 300 seconds and does not stream output incrementally. Executes a shell command inside the sandbox and returns stdout, stderr, and exit code. The sandbox must be in Running phase. The command runs in a non-interactive shell (no TTY).

Get sandbox logs GET

Next Page