Create Sandbox
curl --request POST \
--url https://app.opencomputer.dev/api/sandboxes \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"templateID": "<string>",
"timeout": 123,
"cpuCount": 123,
"memoryMB": 123,
"burst": true,
"envs": {},
"metadata": {},
"image": {},
"snapshot": "<string>",
"webhooks": [
{}
],
"previewAuth": {}
}
'import requests
url = "https://app.opencomputer.dev/api/sandboxes"
payload = {
"templateID": "<string>",
"timeout": 123,
"cpuCount": 123,
"memoryMB": 123,
"burst": True,
"envs": {},
"metadata": {},
"image": {},
"snapshot": "<string>",
"webhooks": [{}],
"previewAuth": {}
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
templateID: '<string>',
timeout: 123,
cpuCount: 123,
memoryMB: 123,
burst: true,
envs: {},
metadata: {},
image: {},
snapshot: '<string>',
webhooks: [{}],
previewAuth: {}
})
};
fetch('https://app.opencomputer.dev/api/sandboxes', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.opencomputer.dev/api/sandboxes",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'templateID' => '<string>',
'timeout' => 123,
'cpuCount' => 123,
'memoryMB' => 123,
'burst' => true,
'envs' => [
],
'metadata' => [
],
'image' => [
],
'snapshot' => '<string>',
'webhooks' => [
[
]
],
'previewAuth' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.opencomputer.dev/api/sandboxes"
payload := strings.NewReader("{\n \"templateID\": \"<string>\",\n \"timeout\": 123,\n \"cpuCount\": 123,\n \"memoryMB\": 123,\n \"burst\": true,\n \"envs\": {},\n \"metadata\": {},\n \"image\": {},\n \"snapshot\": \"<string>\",\n \"webhooks\": [\n {}\n ],\n \"previewAuth\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://app.opencomputer.dev/api/sandboxes")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"templateID\": \"<string>\",\n \"timeout\": 123,\n \"cpuCount\": 123,\n \"memoryMB\": 123,\n \"burst\": true,\n \"envs\": {},\n \"metadata\": {},\n \"image\": {},\n \"snapshot\": \"<string>\",\n \"webhooks\": [\n {}\n ],\n \"previewAuth\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.opencomputer.dev/api/sandboxes")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"templateID\": \"<string>\",\n \"timeout\": 123,\n \"cpuCount\": 123,\n \"memoryMB\": 123,\n \"burst\": true,\n \"envs\": {},\n \"metadata\": {},\n \"image\": {},\n \"snapshot\": \"<string>\",\n \"webhooks\": [\n {}\n ],\n \"previewAuth\": {}\n}"
response = http.request(request)
puts response.read_body{
"sandboxID": "sb-abc123",
"status": "running",
"region": "use2",
"workerID": "w-use2-abc123",
"previewAuthToken": "qx2sSi5IYXWBvnnRqwK9Ky_cIAI-x0Vx1bPCt0XMxsI",
"webhooks": [
{ "id": "whk_3f9a2c", "url": "https://app.example.com/oc-webhook", "secret": "whsec_Hk9…" }
]
}
Sandboxes
Create Sandbox
POST
/
api
/
sandboxes
Create Sandbox
curl --request POST \
--url https://app.opencomputer.dev/api/sandboxes \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"templateID": "<string>",
"timeout": 123,
"cpuCount": 123,
"memoryMB": 123,
"burst": true,
"envs": {},
"metadata": {},
"image": {},
"snapshot": "<string>",
"webhooks": [
{}
],
"previewAuth": {}
}
'import requests
url = "https://app.opencomputer.dev/api/sandboxes"
payload = {
"templateID": "<string>",
"timeout": 123,
"cpuCount": 123,
"memoryMB": 123,
"burst": True,
"envs": {},
"metadata": {},
"image": {},
"snapshot": "<string>",
"webhooks": [{}],
"previewAuth": {}
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
templateID: '<string>',
timeout: 123,
cpuCount: 123,
memoryMB: 123,
burst: true,
envs: {},
metadata: {},
image: {},
snapshot: '<string>',
webhooks: [{}],
previewAuth: {}
})
};
fetch('https://app.opencomputer.dev/api/sandboxes', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.opencomputer.dev/api/sandboxes",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'templateID' => '<string>',
'timeout' => 123,
'cpuCount' => 123,
'memoryMB' => 123,
'burst' => true,
'envs' => [
],
'metadata' => [
],
'image' => [
],
'snapshot' => '<string>',
'webhooks' => [
[
]
],
'previewAuth' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.opencomputer.dev/api/sandboxes"
payload := strings.NewReader("{\n \"templateID\": \"<string>\",\n \"timeout\": 123,\n \"cpuCount\": 123,\n \"memoryMB\": 123,\n \"burst\": true,\n \"envs\": {},\n \"metadata\": {},\n \"image\": {},\n \"snapshot\": \"<string>\",\n \"webhooks\": [\n {}\n ],\n \"previewAuth\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://app.opencomputer.dev/api/sandboxes")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"templateID\": \"<string>\",\n \"timeout\": 123,\n \"cpuCount\": 123,\n \"memoryMB\": 123,\n \"burst\": true,\n \"envs\": {},\n \"metadata\": {},\n \"image\": {},\n \"snapshot\": \"<string>\",\n \"webhooks\": [\n {}\n ],\n \"previewAuth\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.opencomputer.dev/api/sandboxes")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"templateID\": \"<string>\",\n \"timeout\": 123,\n \"cpuCount\": 123,\n \"memoryMB\": 123,\n \"burst\": true,\n \"envs\": {},\n \"metadata\": {},\n \"image\": {},\n \"snapshot\": \"<string>\",\n \"webhooks\": [\n {}\n ],\n \"previewAuth\": {}\n}"
response = http.request(request)
puts response.read_body{
"sandboxID": "sb-abc123",
"status": "running",
"region": "use2",
"workerID": "w-use2-abc123",
"previewAuthToken": "qx2sSi5IYXWBvnnRqwK9Ky_cIAI-x0Vx1bPCt0XMxsI",
"webhooks": [
{ "id": "whk_3f9a2c", "url": "https://app.example.com/oc-webhook", "secret": "whsec_Hk9…" }
]
}
Create a new sandbox.
The 1 GB tier provides 1 vCPU on a best-effort basis. For guaranteed CPU allocation, use the 4 GB tier or above.
If both
string
Template name (default:
"base")integer
Idle timeout in seconds (default:
300)integer
CPU cores. If omitted but
memoryMB is set, inferred automatically.integer
Memory in MB. If omitted but
cpuCount is set, inferred automatically.boolean
Create a Burst Sandbox. Disk is preserved across infrastructure restarts; processes may restart.
cpuCount and memoryMB are provided, they must match a platform tier.
object
Environment variables as key-value pairs
object
Arbitrary key-value pairs
object
Declarative image manifest (see Image builder)
string
Name of a pre-built snapshot for instant boot
object[]
Register webhook destination(s) for this sandbox’s lifecycle events, pinned to this sandbox. Registering inline (rather than via a separate call) means the endpoints exist before
sandbox.created / sandbox.ready are relayed, so you don’t miss the first events.url(string, required): HTTPS endpoint.secret(string): signing secret; omit and one is generated and returned on the response (webhooks[].secret), also re-fetchable later.eventTypes(string[]): event-type allow-list (default all).
POST /api/webhooks): a non-HTTPS url or unknown eventTypes is rejected with 400. Registration is otherwise best-effort — if a spec fails to register downstream, the sandbox is still created; inspect the echoed webhooks: [{ id, url, secret? }] to see what registered.object
Opt in to bearer-token authentication on the sandbox’s preview URLs. When set, every request to
https://sb-<id>-p<port>.<domain> must include an Authorization: Bearer <token> (or X-OC-Preview-Token: <token>) header; missing or wrong → 401.scheme(string): must be"bearer". Reserved for HMAC/JWT later.token(string):"auto"(or omitted) → server generates a 256-bit random token. An explicit string of at least 16 characters lets you bring your own.
previewAuthToken; only its SHA-256 hash is stored. Use POST /api/sandboxes/{id}/preview/rotate to mint a new one.Omit this field for the legacy open behavior — preview URLs respond to anyone who can reach the hostname.{
"sandboxID": "sb-abc123",
"status": "running",
"region": "use2",
"workerID": "w-use2-abc123",
"previewAuthToken": "qx2sSi5IYXWBvnnRqwK9Ky_cIAI-x0Vx1bPCt0XMxsI",
"webhooks": [
{ "id": "whk_3f9a2c", "url": "https://app.example.com/oc-webhook", "secret": "whsec_Hk9…" }
]
}
previewAuthToken is only present when previewAuth was set in the request — read it once and store it durably; the server will not return it again. webhooks is present only when webhooks were requested; each secret (whsec_…) is returned here and stays re-fetchable via GET /api/webhooks/{id}/secret.