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

List active sandboxes or history

List active sandboxes by default, including paused sandboxes. Select history to see non-ephemeral sandboxes that ended in the last 24 hours. Active sandboxes are ordered newest first. Set state=exited for history, ordered by end time. Pages query the selected view before pagination. A record can lag a running sandbox by a few seconds; getSandbox answers from the host.

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 list

orl sandbox list
GET
/v1/sandboxes

Authorization

apiKey
headerAuthorizationBearer <token>

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

Query Parameters

limit?integer
Range1 <= value <= 200
Default50
cursor?string
state?string

running (the default) selects active sandboxes, including paused ones; exited selects the last 24 hours of non-ephemeral history. Cursors belong to their selected view.

Value in"running""exited"

Response Body

Page of sandboxes

application/json
  1. response
data*array<>
nextCursor?string

Opaque; pass back to continue. Absent means no more pages.

Example Request
curl -X GET 'https://api.openrelay.inc/v1/sandboxes'
Example Response
{  "data": [    {      "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"        }      }    }  ],  "nextCursor": "string"}

Overview

Sandboxes: isolated virtual machines that start in milliseconds, run a command and stop, with files, ports and an interactive terminal. Served at the API endpoint (api.openrelay.inc); a sandbox's exposed ports answer on its own host under sandbox.openrelay.inc. Sandbox access is enabled per organization; without it these endpoints return 404.

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.