These limits are enforced by the public v2 API:
| Input | Limit or default |
|---|---|
| JSON request body | 128 KiB maximum |
| Workspaces per account | 10 |
| Sandbox account capacity | Account-specific Sandbox-count and workspace-storage limits; stopped Sandboxes count toward both |
| Workspace name | 1–80 characters and must contain a non-whitespace character |
| Sandbox name | 1–80 characters when supplied |
| Sandbox size | VM-only string small or large; defaults to small |
Idempotency-Key |
1–255 visible ASCII characters for ordinary mutations; required to create a workspace, explicitly request vmSandbox: true, or start an operation; optional when the VM selector is omitted or when starting an existing Sandbox; successful responses replay for 24 hours. Selected TCP service create/lookup instead require the same lowercase UUIDv4 operation key |
| VM Sandbox beta | New creation is VM-only: omitted vmSandbox (or true) creates a VM; false returns 400 INVALID_REQUEST. size selects small (default, 0.5 vCPU / 1,024 MiB) or large (1.5 vCPU / 3,072 MiB); both default to a 30 GiB thin-provisioned workspace, no automatic lifetime expiry, and no libraries or shared volumes. blockNetwork defaults to false (outbound public IPv4 and DNS); true creates no network interface |
| Continuous VM uptime | Maintenance sleep is requested after about 42 hours, even with activity; idle sleep can happen sooner. Disk and Sandbox are retained, but processes and connections stop. Resume the same Sandbox; no automatic expiry is not an uptime guarantee |
argv |
1–64 non-empty strings |
Each argv entry |
8,192 characters maximum |
cwd |
/workspace or a path below it; defaults to /workspace |
| Environment | 64 variables maximum; string values and valid variable names |
| Execution timeout | 1–900 whole seconds; defaults to 120 |
| Synchronous or retained operation output | maxOutputBytes is 1–1,048,576 bytes per stream; defaults to 262,144 |
| Operation wait | 0–30 whole seconds; defaults to 30 |
| Operation output page | 1–262,144 decoded bytes; defaults to 65,536 |
| Terminal operation retention | 24 hours, including up to maxOutputBytes from each stream |
| File path | /workspace or a path below it, without . or .. segments; 4,096 characters maximum |
| Log query entries | 1–5,000; defaults to 1,000 |
| Deleted Sandbox history | Up to 100 newest records returned; records retained about 15 months; no compute, storage or restore controls |
| Deleted Sandbox logs | Same 1–5,000-entry filters as current logs; available only within provider log retention, nominally about 30 days |
| File range read | 8 MiB maximum per response; offset defaults to 0 and maxBytes defaults to 8 MiB |
| File write or conditional edit | 8 MiB maximum complete file |
| Conditional file edit | Complete file must be UTF-8; oldText is 1–65,536 characters and newText is 0–65,536 characters |
| Directory listing page | 1–1,000 immediate entries; pageSize defaults to 1,000 |
| File continuation cursor | Opaque, path-bound, and 4,096 characters maximum |
| VM browser preview | One active HTTP/WebSocket tunnel per owned running network-enabled VM; one selected port from 1–65,535; fixed lifetime of at most one hour |
| VM browser preview URL | Random bearer capability; application restarts preserve the URL and original deadline, reopening only while the VM is running. Reconnect interrupted requests/WebSockets; explicit close, expiry, VM stop or guest tunnel loss can end the link. Public v2 has no keep-open or always-on controls; no UDP, SSH or general ingress |
| Cooperative connection grant | Operator-selected preview only; one nonrenewable grant lasting at most 30 seconds |
| Cooperative connection keys | Exact client_key, ssh_key, and recipient_key formats from OpenAPI; no extra fields |
| Cooperative sealed envelope | Base64, 80–16,000 characters |
| Selected TCP service grant | Generally enabled for an authenticated owner of an active VM; exactly one hour from requested_at, without renewal |
| Selected TCP service ports | 1–8 unique TCP ports from 1–65,535 in strictly ascending order; no UDP or public listener |
| Selected TCP service request | Current Unix-second requested_at, one nonzero Tailcat client_key, one canonical base64 32-byte recipient_key, and no extra fields |
| Selected TCP sealed envelope | Base64, 80–16,000 characters; create is not mutation-retryable, and exact lookup recovers only the original live envelope |
| Usage window | days is bounded to 1–90; defaults to 30 |
| Wallet transaction page | 1–200 newest-first entries; limit defaults to 50; pass nextCursor as before |
| Wallet transaction filters | Inclusive from and exclusive to RFC 3339 timestamps; kind is 1–64 characters, bucket is cash, promo, or plan; before is an opaque cursor of at most 512 characters |
| Sandbox cost-report window | Inclusive from and exclusive to RFC 3339 timestamps; defaults to the last 30 days and can span at most 400 days |
| Sandbox cost detail | Up to 1,000 settled runs; truncated reports omitted additional runs |
| Sandbox analytics resolution | 60–86,400 whole seconds; defaults to 300 |
| Sandbox analytics rate limit | 30 requests per minute per account |
| Sandbox analytics retention | 30 days |
| Audit event page | 1–200 newest-first events; defaults to 50; opaque cursor pagination |
| Audit event retention | GET and HEAD requests for 31 days; writes and key lifecycle events for about 15 months |
| Audit CSV export | Up to 10,000 matching rows from the web activity view |
Errors include a stable machine-readable code and a human-readable error
string:
{ "code": "NOT_FOUND", "error": "Sandbox not found" }Existing integrations may continue reading error; branch on code. Clients
must tolerate new codes added for compatible v2 routes.
| Status | Meaning |
|---|---|
400 |
INVALID_REQUEST for invalid input or new gVisor creation (vmSandbox: false), INVALID_PATH for an unsafe file path, INVALID_RANGE for an invalid file offset, INVALID_CURSOR for invalid continuation, BINARY_FILE for a non-UTF-8 edit, or INVALID_IDEMPOTENCY_KEY for a missing or malformed required key |
401 |
Missing, malformed, unknown, or revoked bearer key |
402 |
INSUFFICIENT_CREDIT because BoxCompute credit is exhausted |
403 |
INSUFFICIENT_SCOPE because the key does not include the route’s required scope, or BILLING_ACCOUNT_FROZEN because the billing account is frozen |
404 |
The active or deleted Sandbox, owned workspace, or requested file was not found |
408 |
Execution timed out at the Sandbox service |
409 |
IDEMPOTENCY_CONFLICT for conflicting key reuse, WORKSPACE_QUOTA_EXCEEDED at 10 workspaces, DESTINATION_EXISTS for a rename collision, EDIT_CONFLICT when edit text is missing or ambiguous, CURSOR_STALE when a continued file or directory changed, or an existing preview tunnel when another VM preview is requested |
412 |
PRECONDITION_FAILED because a file changed after the caller read it |
413 |
A JSON body or bounded file transfer exceeds its route limit |
415 |
A JSON mutation or binary file upload has the wrong media type |
429 |
RATE_LIMITED because the per-account Sandbox analytics request limit was exceeded, or WORKSPACE_QUOTA_EXCEEDED because Sandbox-count or retained workspace-storage capacity is full |
502 |
The Sandbox service is currently unavailable |
503 |
The Sandbox runtime, retained-log store, or preview transport is currently unavailable; preview close can also return 503 after disabling the URL when transport cleanup remains pending |
A command that exits non-zero still returns a successful HTTP response. Check result.exitCode and result.timedOut. Also check stdoutTruncated and stderrTruncated before assuming output is complete.
The official SDKs raise BoxComputeError for API responses and expose its status, stable code,
message, request ID when available, and retryable flag. Network failures raise
BoxComputeTransportError. A transport error does not prove whether a mutation reached the service;
use idempotency keys for supported create and operation-start retries.
The public v2 routes do not expose customer APIs for workspace deletion, SDK-specific lifecycle handles, streaming command output, streaming file I/O, a generally available interactive shell or PTY, shared volumes, checkpoints, or forks. VM browser previews expose one HTTP/WebSocket port through a bearer URL for at most one hour; they are not UDP, SSH, permanent hosting, or general ingress, and current SDKs and the CLI do not expose their controls. A separate default-off cooperative connection preview exists only for operator-selected Sandboxes and is not general SSH availability. Generally enabled selected-TCP access opens 1–8 requested ports on an owned active VM to one client for one hour; it is not a public listener or exposed by current SDKs and the CLI. Observable operations provide polling, retained output, and explicit cancellation for one structured command; they are not a general-purpose process or PTY API.