Create and manage managed sandboxes: VMs on platform engines that run belt remote start and connect back as an ordinary remote. Use a sandbox's remote_id with the Remotes and Exec runs APIs the same way as a machine you registered yourself.
Requires API key scopes sandboxes:read (list, get) and sandboxes:write (create, start, stop, delete). The standard preset includes both. The key a box holds has the remote preset's scopes only, so a box cannot create sandboxes.
Sandboxes are open to every workspace. Create and start are refused only when the workspace's feature:sandboxes entitlement is set to enabled: false: 403 feature_not_available, detail sandboxes are turned off for this workspace.
→ Remotes API · Exec runs API · Managed sandboxes
Concepts
| Term | Description |
|---|---|
| Sandbox | A workspace record for one managed VM. The API places it on a free worker of a platform engine, mints a key for the box, and handles start, stop, restarts and billing. |
| Remote | Created with the sandbox and kept across restarts. The box registers as this remote. |
| Generation | Goes up on every start, including automatic restarts. Each generation boots on a fresh disk with a new box key; the remote id stays the same. |
Sandboxes run only on platform engines that report the sandboxes engine capability, never on your private engines.
Inside the box, INFERENCE_API_URL points at the API. The box key reaches the box as a bound secret for the API's host only: the box holds a placeholder, and the engine's egress gateway puts the key on requests to the API.
Lifecycle
status | Meaning |
|---|---|
pending | Wants to run; waiting for worker capacity, credit, or a restart backoff |
starting | Sent to the engine |
running | The VM is up (its remote may still be connecting) |
stopping | Stop sent |
stopped | Box stopped; the record and remote remain |
failed | Gave up; see status_reason |
desired_state | Set by |
|---|---|
running | Create, POST /sandboxes/{id}/start, or an automatic restart |
stopped | POST /sandboxes/{id}/stop |
deleted | DELETE /sandboxes/{id} |
status_reason values include no capacity, out of credit and the engine went away. A box that ends on its own, or whose remote stays disconnected for 3 minutes, restarts after 5 s, 30 s, then 2 min, at most 3 times in 10 minutes; after that it is failed.
Billing
A running box is charged to the owner's balance every minute, at the leased worker's price, for the time it is healthy: its remote connected and heartbeating. Time the remote is away (no heartbeat for a minute) or disconnected is not billed. With no balance, a new generation does not start (status_reason out of credit).
Create sandbox
POST /sandboxes
Requires sandboxes:write. Creates the sandbox and its remote, with desired_state running. A server with no box image configured answers 409 sandboxes are not set up on this server (no SANDBOX_IMAGE).
| Field | Type | Description |
|---|---|---|
name | string | Display name |
vcpus | integer | Default 2, max 8 |
memory_mib | integer | Default 4096, max 16384 |
disk_mib | integer | Default 10240, max 51200 |
1curl -X POST https://api.inference.sh/sandboxes \2 -H "Authorization: Bearer inf_your_key" \3 -H "Content-Type: application/json" \4 -d '{"name":"dev-box"}'Returns the sandbox.
List sandboxes
GET /sandboxes or POST /sandboxes/list
Requires sandboxes:read. Cursor-paginated like other list routes.
Get sandbox
GET /sandboxes/{id}
Requires sandboxes:read.
Start sandbox
POST /sandboxes/{id}/start
Requires sandboxes:write. Sets desired_state to running. A stopped or failed sandbox goes back to pending and boots on a new disk as the same remote. A start asked for while stopping runs when the stop finishes.
Stop sandbox
POST /sandboxes/{id}/stop
Requires sandboxes:write. Stops the VM and drops its disk. The sandbox and its remote stay, so you can start it again.
Delete sandbox
DELETE /sandboxes/{id}
Requires sandboxes:write. Stops a live box, then removes the sandbox and its remote.
Sandbox fields
| Field | Type | Description |
|---|---|---|
id | string | Sandbox id |
user_id, team_id | string | Owner |
name | string | Display name |
image | string | Box image the platform boots |
vcpus, memory_mib, disk_mib | integer | Size |
desired_state | string | running, stopped or deleted |
status | string | See Lifecycle |
status_reason | string | Why it is pending or failed |
generation | integer | Starts so far, restarts included |
engine_id, worker_id | string | Placement of the current generation; empty while pending or stopped |
remote_id | string | The remote the box connects as |
started_at, stopped_at | string | Timestamps, when set |
SDKs
Neither SDK has a client.sandboxes namespace; call the routes above. SandboxDTO, CreateSandboxRequest, the SandboxStatus and SandboxDesiredState values, EngineCapabilitySandboxes and ResourceFeatureSandboxes ship in the next JavaScript and Python SDK releases.