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

Pause a sandbox

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.

Required permission

Requires the sandboxes.pause 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 pause

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

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, paused

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/pause'
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"    }  }}

Answer a fresh signed URL for a signed port POST

Issues a fresh signed URL for an exposed signed port. Its validity defaults to 3600 seconds and cannot extend past the sandbox's end. Set expiresInSeconds to choose its validity. A port that is not exposed answers 404 PORT_NOT_EXPOSED, and a public one answers 400.

Resume a paused sandbox POST

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.