Activate a sandbox
Returns the sandbox with a fresh access token. If the sandbox is paused, it is resumed first; a pause still finishing is waited out briefly, then resumed. Idempotent — calling it on an active sandbox just returns a new token.
curl --request POST \
--url https://api.superserve.ai/sandboxes/{sandbox_id}/activate \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.superserve.ai/sandboxes/{sandbox_id}/activate"
headers = {"X-API-Key": "<api-key>"}
response = requests.post(url, headers=headers)
print(response.text)const options = {method: 'POST', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api.superserve.ai/sandboxes/{sandbox_id}/activate', 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://api.superserve.ai/sandboxes/{sandbox_id}/activate",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"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"
"net/http"
"io"
)
func main() {
url := "https://api.superserve.ai/sandboxes/{sandbox_id}/activate"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.superserve.ai/sandboxes/{sandbox_id}/activate")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.superserve.ai/sandboxes/{sandbox_id}/activate")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"id": "<string>",
"name": "<string>",
"status": "active",
"vcpu_count": 123,
"memory_mib": 123,
"snapshot_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"source_snapshot_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"created_at": "2023-11-07T05:31:56Z",
"timeout_seconds": 123,
"auto_delete_seconds": 123,
"auto_delete_at": "2023-11-07T05:31:56Z",
"network": {
"allow_out": [
"api.openai.com",
"*.github.com",
"8.8.8.8/32"
],
"deny_out": [
"0.0.0.0/0"
]
},
"metadata": {
"env": "prod",
"owner": "agent-7"
},
"preview_access": "legacy_public",
"routing_hint": "<string>",
"access_token": "<string>",
"secrets": [
{
"env_key": "<string>",
"secret_name": "<string>",
"revoked": false
}
]
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}Authorizations
Path Parameters
The unique identifier of the sandbox.
Public sandbox ID: a bare UUID, or the region-tagged form sb-<region>-<uuid> (e.g. sb-use-1b4e28ba-…). Treat as an opaque string; the tagged form routes the request to the sandbox's home region. Endpoints accept both forms interchangeably.
^(sb-[a-z0-9]+-)?[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$Response
The sandbox is active.
Single-sandbox shape — SandboxListItem plus access_token and bound secrets.
Public sandbox ID: a bare UUID, or the region-tagged form sb-<region>-<uuid> (e.g. sb-use-1b4e28ba-…). Treat as an opaque string; the tagged form routes the request to the sandbox's home region. Endpoints accept both forms interchangeably.
^(sb-[a-z0-9]+-)?[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$Current state of the sandbox. active means running; paused means paused and awaiting resume. pausing, resuming and migrating are transient states observed while the platform pauses, restores, or relocates a sandbox (e.g. after a 202 from /pause, or auto-resume on /exec); clients should poll or retry shortly. failed means the sandbox can no longer be resumed.
active, pausing, paused, resuming, migrating, failed ID of the latest snapshot (present after a pause).
The saved snapshot the sandbox was created from, when it was.
Auto-pause timeout in seconds, if configured. Absent when auto-pause is disabled.
Garbage-collection window for the paused state, if configured. Absent when auto-delete is disabled.
When the sandbox will be deleted. Present only while the sandbox is paused with auto_delete_seconds configured. The deadline is armed when the sandbox pauses (or when the setting is applied to an already-paused sandbox) and cleared on resume.
Current egress allow/deny rules, if any have been configured. Absent when the sandbox uses default network settings.
Show child attributes
Show child attributes
User-supplied tags attached at creation. Always present — sandboxes created without metadata return {} rather than being absent.
Show child attributes
Show child attributes
{ "env": "prod", "owner": "agent-7" }
Default access for newly published ports. public and private
are strict modes; existing published rows keep their own access.
legacy_public may be returned for an older sandbox and preserves
all-port behavior until updated to a strict mode.
legacy_public, public, private Optional signed logical-owner routing hint. Send on data-plane requests as X-Superserve-Routing-Hint, or as a route. WebSocket subprotocol alongside the unchanged access token. Refresh after resume/activate; absent or invalid hints retain ownership lookup fallback. This does not authorize access.
Per-sandbox access token for data-plane operations (file
upload/download, terminal). Pass as the X-Access-Token
header.
Credentials bound to this sandbox. Each entry maps an env-var name visible to the agent to the secret name it resolves to. revoked=true when the underlying secret has been soft-deleted (the env var still holds the now-useless proxy token).
Show child attributes
Show child attributes
curl --request POST \
--url https://api.superserve.ai/sandboxes/{sandbox_id}/activate \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.superserve.ai/sandboxes/{sandbox_id}/activate"
headers = {"X-API-Key": "<api-key>"}
response = requests.post(url, headers=headers)
print(response.text)const options = {method: 'POST', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api.superserve.ai/sandboxes/{sandbox_id}/activate', 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://api.superserve.ai/sandboxes/{sandbox_id}/activate",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"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"
"net/http"
"io"
)
func main() {
url := "https://api.superserve.ai/sandboxes/{sandbox_id}/activate"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.superserve.ai/sandboxes/{sandbox_id}/activate")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.superserve.ai/sandboxes/{sandbox_id}/activate")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"id": "<string>",
"name": "<string>",
"status": "active",
"vcpu_count": 123,
"memory_mib": 123,
"snapshot_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"source_snapshot_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"created_at": "2023-11-07T05:31:56Z",
"timeout_seconds": 123,
"auto_delete_seconds": 123,
"auto_delete_at": "2023-11-07T05:31:56Z",
"network": {
"allow_out": [
"api.openai.com",
"*.github.com",
"8.8.8.8/32"
],
"deny_out": [
"0.0.0.0/0"
]
},
"metadata": {
"env": "prod",
"owner": "agent-7"
},
"preview_access": "legacy_public",
"routing_hint": "<string>",
"access_token": "<string>",
"secrets": [
{
"env_key": "<string>",
"secret_name": "<string>",
"revoked": false
}
]
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}