Skip to content
OpenRelay is in early access, and the /v1 API is stable. New capabilities ship in the changelog.
Skip to Content
PricingDashboard
GuidesAPI ReferenceCLI
API ReferenceComputeSandboxes

Resume a paused sandbox

Restores a paused sandbox on the same host, preserving its files and processes. Resuming a sandbox that is already running is safe. A host with no room for it now answers 503 CAPACITY_EXHAUSTED and the sandbox stays paused: retry after Retry-After.

Required permission

Requires the sandboxes.resume permission. See Permissions for the roles and API key permissions that include it.

Command line

The orl CLI wraps this endpoint:

Guided workflow: orl sandbox resume

orl sandbox resume <sandbox-id>
POST
/v1/sandboxes/{sandboxId}/resume

Authorization

apiKey
headerAuthorizationBearer <token>

OpenRelay API key. Send it as Authorization: Bearer or_… (legacy vl_… keys still work).

Path Parameters

sandboxId*string

Response Body

The sandbox, running

application/json
  1. response
id*string

Opaque; do not parse it.

template*string
state*string

paused is a sandbox its owner paused, until it is resumed. Its timeout counts on.

Value in"running""paused""exited"
createdAt*string
Formatdate-time
expiresAt*string
Formatdate-time
endedAt?string
Formatdate-time
exitReason?string

Why the sandbox ended. Absent while it runs.

Value in"killed""timeout""guest_exit""host_drain""error""lost""host_lost"
groupId?string

The group it was created in, if any.

metadata?
ephemeral?boolean

True when this sandbox leaves no customer history after it ends.

result?
Example Request
curl -X POST 'https://api.openrelay.inc/v1/sandboxes/string/resume'
Example Response
{  "id": "string",  "template": "string",  "state": "running",  "createdAt": "2019-08-24T14:15:22Z",  "expiresAt": "2019-08-24T14:15:22Z",  "endedAt": "2019-08-24T14:15:22Z",  "exitReason": "killed",  "groupId": "string",  "metadata": {    "property1": "string",    "property2": "string"  },  "ephemeral": true,  "result": {    "execId": "string",    "exitCode": 0,    "stdout": "string",    "stderr": "string",    "truncated": true,    "error": {      "error": "string",      "code": "string",      "permission": "string",      "deniedBy": "string",      "policies": [        "string"      ],      "requestId": "string"    }  }}

Pause a sandbox POST

Saves a sandbox's memory and disk on its host, then stops it to release CPU and memory. Resume restores its files and processes. Answers once the snapshot is written. Open connections do not survive. While paused it is charged for neither CPU nor memory, its timeout still counts, and every call that needs it running answers 409 SANDBOX_PAUSED until resume; get, list and kill answer as usual. Pausing a paused sandbox answers it as it is, so a retry is safe.

Create many sandboxes as one group POST

Starts a group of sandboxes, reserving at least minReady together. Streams group progress and each sandbox as capacity becomes available. Starts the rest as capacity allows, until all n run or waitSeconds expires. The answer is a stream with a group line, one sandbox line per member as it starts, and, if some never fit, a last error line with code CAPACITY_EXHAUSTED and the count started. A 503 means minReady never fit together within waitSeconds, and nothing was started.