Create a sandbox
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.
Required permission
Requires the sandboxes.create 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 create
orl sandbox create --template <template>apiKeyAuthorizationBearer <token>OpenRelay API key. Send it as Authorization: Bearer or_… (legacy vl_… keys still work).
Idempotency-Key?stringMakes a retried create safe. Choose one value per create you mean to make, 1 to 512 bytes (bytes, not characters), such as a UUID, and send it again on every retry of that create. The first request with a key runs, and a 2xx answer is kept for 24 hours: a repeat with the same key and the same body gets that answer back, with the same status and the header Idempotent-Replayed: true, and creates nothing. A batch create compares the body byte for byte; a VM or pod create compares the fields it decodes, so whitespace and key order do not count. A repeat while the first request is still running answers 409; repeat it a second later. The same key with a different body answers 422. An answer other than a 2xx is not kept, so a retry after a 4xx or a 5xx runs again. A 2xx too large to keep holds the key without it: every repeat answers 409 and creates nothing. Keys are scoped to the organization and the operation.
1 <= lengthX-Resume-From?integerOn a replayed create, the seq of the last line already read. The stream resumes after it.
0 <= valueapplication/json- body
template*stringA template id from GET /v1/sandbox-templates: a built-in or one of the organization's.
run?cpu?integerThe sandbox's vCPUs, its cgroup's limit. Every sandbox is restored from its template's snapshot and has the template's machine: absent, the sandbox gets the template's vCPUs, and more than the template's is refused with RESOURCES_EXCEED_TEMPLATE.
1 <= valuememoryMiB?integerThe sandbox's memory in MiB, its cgroup's limit. Absent, the template's; more than the template's is refused with RESOURCES_EXCEED_TEMPLATE, as for cpu.
cpuRequest?numberThe vCPUs a shared sandbox is counted and billed for at least, to the thousandth, at most cpu. cpu stays its limit. A pinned sandbox's request is its cpu. Ignored unless the organization has requests.
0.25 <= value0.25memoryRequestMiB?integerThe memory a shared sandbox is counted and billed for at least, at most memoryMiB, which stays its limit: the guest may grow past its request to its limit. A pinned sandbox's request is its memoryMiB. Ignored unless the organization has requests.
128 <= value128timeoutSeconds?integervalue <= 86400300placement?string"shared""shared""pinned"env?egress?network?The sandbox's network policy layer, a ceiling under the organization's, its user's and its key's. Not with egress. Absent, and with no egress, the organization's defaults apply. Refused (400) unless the organization has sandbox network policy.
metadata?ephemeral?booleanOmit customer history when the sandbox ends. Running commands keep their normal lifetime; completing a command does not stop the sandbox.
falsewaitSeconds?integerHow long the request may wait for capacity before it answers 503 CAPACITY_EXHAUSTED. A longer wait is cut to the maximum.
0 <= value <= 12010autoPause?booleanConsent to be snapshotted to disk when the host needs the memory, and woken by the next operation on the sandbox. Its processes stop for that long and its TCP connections end; the time on disk is not charged. Ignored unless the organization has auto-pause.
falseThe sandbox. With run set, application/json waits for the command to exit and carries its result; application/x-ndjson streams it.
- response
id*stringOpaque; do not parse it.
template*stringstate*stringpaused is a sandbox its owner paused, until it is resumed. Its timeout counts on.
"running""paused""exited"createdAt*stringdate-timeexpiresAt*stringdate-timeendedAt?stringdate-timeexitReason?stringWhy the sandbox ended. Absent while it runs.
"killed""timeout""guest_exit""host_drain""error""lost""host_lost"groupId?stringThe group it was created in, if any.
metadata?ephemeral?booleanTrue when this sandbox leaves no customer history after it ends.
result?curl -X POST 'https://api.openrelay.inc/v1/sandboxes' \ -H 'Content-Type: application/json' \ -d '{ "template": "python", "run": { "cmd": "python -c '\''print(6*7)'\''" }}'{ "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" } }}List active sandboxes or history GET
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.
Get a sandbox GET
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.