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 running-VM, Sandbox-count and workspace-storage limits across all workspaces; stopped Sandboxes still count toward Sandbox-count and storage limits |
| 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, large, xl or xxl; defaults to small. XL and XXL are included with Starter or available through per-size early access; accounts without access receive 403 FEATURE_ACCESS_DENIED. See size eligibility |
| Sandbox metadata | Immutable, at most 16 string pairs; keys 1–63 characters matching ^[A-Za-z0-9][A-Za-z0-9._/-]{0,62}$, values at most 256 characters without control characters. List filters use the same limits with unique keys and exact AND matching |
| Automatic VM wake-up | autoResume defaults to true; false makes execute, operation start and file calls on a stopped VM return 409 SANDBOX_STOPPED. Explicit start is still supported |
| VM root disk | diskGiB: whole number from 10–30, defaults to 30; includes the OS and /workspace. Below 30 requires early access or returns 400 INVALID_REQUEST. Immutable; counts in full against storage while stopped too |
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. See the four compute sizes. All default to a 30 GiB thin-provisioned root disk, no automatic lifetime expiry, and no libraries or shared volumes. blockNetwork defaults to false (outbound public IPv4 and DNS); true creates no network interface |
| Outbound mail | TCP port 25 is blocked for all Sandboxes; connection attempts time out. This restriction does not block authenticated submission on 465/587 or HTTPS mail APIs in network-enabled Sandboxes |
| Idle VM stop | 30 minutes after the last API call that used the VM (what counts); stop it sooner with POST /api/v2/sandboxes/:id/stop |
| 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. A VM stop ends a plain link; create a new preview after restart. Public v2 has no keep-open or always-on controls; no UDP, SSH or general ingress |
| VM desktop | Running, network-enabled Large, XL or XXL; 1280 × 800 screen; never wakes the VM. Screenshot PNG/JPEG up to 8 MiB; one action per request; ASCII typing up to 4,096 bytes; screenshot settling 0–2,000 ms |
| Desktop viewer | Bearer URL grants viewing and input, not read-only access; one viewer at a time. Repeated request sets expiry to one hour from the request, at most 24 hours after link creation; deployment or key revocation can end it early |
| 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 |
Free up account capacity
These are the current hosted allowances across all of an account’s workspaces:
| Account | Running VMs | Total VMs | Reserved VM disk |
|---|---|---|---|
| Free | Up to 2 | Up to 8, subject to storage | 120 GiB: four VMs at the default 30 GiB each |
| Starter subscriber | All VMs the account holds, up to 8; no separate running cap | Up to 8 | 240 GiB: eight VMs at the default 30 GiB each |
Allow about a minute for a subscription change to reach VM admission. Higher allowances do not remove compute charges, credit checks, idle stops or maintenance stops. The free running limit applies to accounts without a qualifying subscription, purchased credit, or provisioned organization access. Account-specific allowances can differ.
The app’s Sandboxes page shows total VMs and reserved storage against the account’s limits. Free accounts also have a Running bar; Starter shows the running count beside VMs instead. Each VM reserves its full declared disk size even when stopped: a 30 GiB VM containing 2 GiB of files still counts as 30 GiB toward the storage limit. An early-access account choosing a smaller disk reserves that chosen size instead; the VM-count limit and any separate running-VM limit still apply.
If the running-VM limit is full, use Stop on a running VM you no longer need, or ask the agent
to stop the VM you choose. Stopping ends its processes and compute billing but keeps its disk and
files; the agent follows your approval settings. MCP clients can use sandbox_stop, and HTTP
clients the stop route.
If storage or total-VM capacity is full, stopping does not free room. Download needed files before
deleting a VM you no longer need; deletion erases its disk. A failed new allocation does not mean
the VMs you already have cannot be used. See Sandbox lifecycle.
Handle errors
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 lacks the required scope, ACCOUNT_SUSPENDED because its account is suspended, or BILLING_ACCOUNT_FROZEN because billing is frozen. For suspension, contact support@boxcompute.ai; retries or additional scopes do not restore access |
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 running-VM, 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 |
Additional desktop and lifecycle errors: 409 SANDBOX_STOPPED requires explicit VM start when
auto-resume is disabled; 409 DESKTOP_UNAVAILABLE requires checking VM/desktop readiness;
409 DESKTOP_BUSY means no input was sent. 502 DESKTOP_INPUT_UNCERTAIN means input may have
run: inspect a screenshot rather than blindly repeating it. 403 FEATURE_ACCESS_DENIED means
the requested XL or XXL size is not enabled for the account. See desktop controls.
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.