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

Get a sandbox

Returns a sandbox's state and details. A running sandbox is read from its host; a sandbox that has ended is read from its stored history. Ended ephemeral sandboxes and history older than 24 hours answer 404.

Required permission

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

orl sandbox get <sandbox-id>
GET
/v1/sandboxes/{sandboxId}

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

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 GET 'https://api.openrelay.inc/v1/sandboxes/string'
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"    }  }}

Create a sandbox POST

Starts a sandbox from a template, optionally running a first command. Collect the result as JSON or stream output as NDJSON. With run set, application/json waits for the command to exit and answers the sandbox with its result; application/x-ndjson streams one SandboxEvent per line, the first naming the sandbox. Send an Idempotency-Key on every create. A repeat with the same key and body answers the same sandbox with Idempotent-Replayed: true, and a repeat with X-Resume-From skips the output it already read. A refusal (429 or 503) keeps nothing, so the next attempt runs again.

Kill a sandbox DELETE

Answers once the VM is stopped; its memory is released and its usage settled after the answer. Killing a sandbox that has ended answers 410.