API reference · In your appSandboxes
Sandboxes
Short-lived development machines for a project, with a terminal and a team-only preview address. Pro plan.
Sandboxes need the Pro plan: on Free, creating or starting one answers 402. The guide is Sandboxes. The terminal itself is a WebSocket, opened with a 60-second ticket from the terminal-ticket call, so it is not listed here as a JSON endpoint.
The sandbox object
Fields
namestringrequiredruntimestringrequiredOne of
node22,python312,go123.sizestringrequiredsmall = 0.5 vCPU, 512 MB, 2 GB disk; large = 1 vCPU, 2 GB, 4 GB disk. Several pack onto one node.
One of
small,large.sourcestring or nullrequiredWhat was cloned (e.g. "storefront · main"); null for an empty machine.
statestringrequiredstoppedis suspended: the disk is kept andstartresumes it.One of
starting,running,stopped.started_atstringrequiredstopped_atstring or nullrequiredstarted_byFlagPersonrequiredShow 4 child fieldsHide child fields
idstringrequirednamestringrequiredemailstringrequiredavatar_urlstring or nullrequired
stop_afterintegerrequiredIdle minutes before it suspends itself.
One of
10,30,60,120.urlstringrequiredThe sandbox's preview URL (port 3000), reachable by team members only.
terminalarray of SandboxTerminalLinerequiredThe boot and run output so far; live output streams over the terminal WebSocket.
Show 2 child fieldsHide child fields
kindstringrequiredOne of
cmd,out,ok,err.textstringrequired
usageSandboxUsagerequiredShow 4 child fieldsHide child fields
cpuintegerrequiredPercent of the size's vCPU in use.
memory_gbnumberrequireddisk_gbnumberrequiredidle_minutesintegerrequiredMinutes since the last activity; drives the idle suspend.
A project's sandboxes
The Sandboxes page: every sandbox, the live ones first and then by most recently started. running counts the live ones (starting or running) and limit is the most a team may run at once, for "2 of 3 running" and to disable Create at the cap. as_of is the server's clock, for the page's relative times. The page polls this while any sandbox is starting.
Permissions: Any team member. A non-member gets 404.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.
Response 200
The sandboxes.itemsarray of SandboxrequiredShow 12 child fieldsHide child fields
namestringrequiredruntimestringrequiredOne of
node22,python312,go123.sizestringrequiredsmall = 0.5 vCPU, 512 MB, 2 GB disk; large = 1 vCPU, 2 GB, 4 GB disk. Several pack onto one node.
One of
small,large.sourcestring or nullrequiredWhat was cloned (e.g. "storefront · main"); null for an empty machine.
statestringrequiredstoppedis suspended: the disk is kept andstartresumes it.One of
starting,running,stopped.started_atstringrequiredstopped_atstring or nullrequiredstarted_byFlagPersonrequiredShow 4 child fieldsHide child fields
idstringrequirednamestringrequiredemailstringrequiredavatar_urlstring or nullrequired
stop_afterintegerrequiredIdle minutes before it suspends itself.
One of
10,30,60,120.urlstringrequiredThe sandbox's preview URL (port 3000), reachable by team members only.
terminalarray of SandboxTerminalLinerequiredThe boot and run output so far; live output streams over the terminal WebSocket.
Show 2 child fieldsHide child fields
kindstringrequiredOne of
cmd,out,ok,err.textstringrequired
usageSandboxUsagerequiredShow 4 child fieldsHide child fields
cpuintegerrequiredPercent of the size's vCPU in use.
memory_gbnumberrequireddisk_gbnumberrequiredidle_minutesintegerrequiredMinutes since the last activity; drives the idle suspend.
runningintegerrequiredLive sandboxes (starting or running).
limitintegerrequiredThe most a team may run at once.
as_ofstringrequiredThe server's clock, for the page's relative times.
Errors
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
Every code is explained in Errors.
curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/sandboxes" \
-H "Authorization: Bearer $ORBITS_TOKEN"{
"items": [
{
"name": "seed-test-data",
"runtime": "node22",
"size": "small",
"source": null,
"state": "starting",
"started_at": "2026-11-10T09:30:00Z",
"stopped_at": "2026-11-10T09:30:00Z",
"started_by": {
"id": "id",
"name": "my-app",
"email": "ada@example.com",
"avatar_url": "https://my-app.theorbits.app"
},
"stop_after": 10,
"url": "https://my-app.theorbits.app",
"terminal": [
{
"kind": "cmd",
"text": "text"
}
],
"usage": {
"cpu": 1,
"memory_gb": 1,
"disk_gb": 1,
"idle_minutes": 1
}
}
],
"running": 1,
"limit": 1,
"as_of": "2026-11-10T09:30:00Z"
}Start a sandbox
Provisions a machine and boots it: state is starting, then running once it is up (poll GET .../sandboxes). clone checks out the project's repository at main; env copies the Preview environment variables in. size caps CPU, memory and disk; stop_after is the idle minutes before it suspends itself. Names are lowercase letters, digits and single dashes, unique among the project's live sandboxes.
A team runs at most SandboxPage.limit sandboxes at once; past that this returns 409 and the page offers to stop one first.
Runtime (v1): a sandbox is a Docker container on the build host, capped by cgroups, with the terminal backed by docker exec. Stronger isolation (Firecracker microVMs) is a later swap that does not change this contract.
Permissions: Owners, admins and members. Viewers get 403.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….Idempotency-KeystringrequiredA new value, such as a UUID, for each change. Resend with the same value and body to retry safely.
From 8 to 128 characters.
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.
Body
application/jsonnamestringrequiredAt most 40 characters.
runtimestringrequiredOne of
node22,python312,go123.sizestringrequiredsmall = 0.5 vCPU, 512 MB, 2 GB disk; large = 1 vCPU, 2 GB, 4 GB disk. Several pack onto one node.
One of
small,large.clonebooleanCheck out the project's repository at main.
Defaults to
false.envbooleanCopy the Preview environment variables in.
Defaults to
false.stop_afterintegerIdle minutes before it suspends itself.
One of
10,30,60,120. Defaults to30.
Response 201
The new sandbox, starting.namestringrequiredruntimestringrequiredOne of
node22,python312,go123.sizestringrequiredsmall = 0.5 vCPU, 512 MB, 2 GB disk; large = 1 vCPU, 2 GB, 4 GB disk. Several pack onto one node.
One of
small,large.sourcestring or nullrequiredWhat was cloned (e.g. "storefront · main"); null for an empty machine.
statestringrequiredstoppedis suspended: the disk is kept andstartresumes it.One of
starting,running,stopped.started_atstringrequiredstopped_atstring or nullrequiredstarted_byFlagPersonrequiredShow 4 child fieldsHide child fields
idstringrequirednamestringrequiredemailstringrequiredavatar_urlstring or nullrequired
stop_afterintegerrequiredIdle minutes before it suspends itself.
One of
10,30,60,120.urlstringrequiredThe sandbox's preview URL (port 3000), reachable by team members only.
terminalarray of SandboxTerminalLinerequiredThe boot and run output so far; live output streams over the terminal WebSocket.
Show 2 child fieldsHide child fields
kindstringrequiredOne of
cmd,out,ok,err.textstringrequired
usageSandboxUsagerequiredShow 4 child fieldsHide child fields
cpuintegerrequiredPercent of the size's vCPU in use.
memory_gbnumberrequireddisk_gbnumberrequiredidle_minutesintegerrequiredMinutes since the last activity; drives the idle suspend.
Errors
- 402The team's plan doesn't include this (see
GET /v1/plans).codeisplan_required,required_planisproandfeaturenames what is missing; show the upgrade dialog. - 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
- 409The request conflicts with current state.
- 422Validation failed, or the Idempotency-Key was reused with a different body.
Every code is explained in Errors.
curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/sandboxes" \
-H "Authorization: Bearer $ORBITS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"name": "seed-test-data",
"runtime": "node22",
"size": "small"
}'{
"name": "seed-test-data",
"runtime": "node22",
"size": "small",
"source": null,
"state": "starting",
"started_at": "2026-11-10T09:30:00Z",
"stopped_at": "2026-11-10T09:30:00Z",
"started_by": {
"id": "id",
"name": "my-app",
"email": "ada@example.com",
"avatar_url": "https://my-app.theorbits.app"
},
"stop_after": 10,
"url": "https://my-app.theorbits.app",
"terminal": [
{
"kind": "cmd",
"text": "text"
}
],
"usage": {
"cpu": 1,
"memory_gb": 1,
"disk_gb": 1,
"idle_minutes": 1
}
}A sandbox, its usage and open ports
The sandbox's page: its usage against the size's ceiling, the terminal output so far, and the ports it listens on (port 3000, team-only, in v1). Use {sandbox} from GET .../sandboxes.
Permissions: Any team member. A non-member gets 404.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.sandboxstringrequiredThe sandbox's name.
Response 200
The sandbox.namestringrequiredruntimestringrequiredOne of
node22,python312,go123.sizestringrequiredsmall = 0.5 vCPU, 512 MB, 2 GB disk; large = 1 vCPU, 2 GB, 4 GB disk. Several pack onto one node.
One of
small,large.sourcestring or nullrequiredWhat was cloned (e.g. "storefront · main"); null for an empty machine.
statestringrequiredstoppedis suspended: the disk is kept andstartresumes it.One of
starting,running,stopped.started_atstringrequiredstopped_atstring or nullrequiredstarted_byFlagPersonrequiredShow 4 child fieldsHide child fields
idstringrequirednamestringrequiredemailstringrequiredavatar_urlstring or nullrequired
stop_afterintegerrequiredIdle minutes before it suspends itself.
One of
10,30,60,120.urlstringrequiredThe sandbox's preview URL (port 3000), reachable by team members only.
terminalarray of SandboxTerminalLinerequiredThe boot and run output so far; live output streams over the terminal WebSocket.
Show 2 child fieldsHide child fields
kindstringrequiredOne of
cmd,out,ok,err.textstringrequired
usageSandboxUsagerequiredShow 4 child fieldsHide child fields
cpuintegerrequiredPercent of the size's vCPU in use.
memory_gbnumberrequireddisk_gbnumberrequiredidle_minutesintegerrequiredMinutes since the last activity; drives the idle suspend.
portsarray of SandboxPortrequiredShow 3 child fieldsHide child fields
portintegerrequiredurlstringrequiredaccessstringrequiredv1 exposes ports to team members only.
One of
team,public.
Errors
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
Every code is explained in Errors.
curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/sandboxes/sbx_01jc8x6e4mq2v7r9y3t5b0zp8w" \
-H "Authorization: Bearer $ORBITS_TOKEN"{
"name": "seed-test-data",
"runtime": "node22",
"size": "small",
"source": null,
"state": "starting",
"started_at": "2026-11-10T09:30:00Z",
"stopped_at": "2026-11-10T09:30:00Z",
"started_by": {
"id": "id",
"name": "my-app",
"email": "ada@example.com",
"avatar_url": "https://my-app.theorbits.app"
},
"stop_after": 10,
"url": "https://my-app.theorbits.app",
"terminal": [
{
"kind": "cmd",
"text": "text"
}
],
"usage": {
"cpu": 1,
"memory_gb": 1,
"disk_gb": 1,
"idle_minutes": 1
},
"ports": [
{
"port": 3000,
"url": "https://my-app.theorbits.app",
"access": "team"
}
]
}Delete a sandbox
Terminates the machine and frees its disk. Irreversible; unlike stop, nothing is kept.
Permissions: Owners, admins and members. Viewers get 403.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.sandboxstringrequiredThe sandbox's name.
Response 204
Deleted. No body.
Errors
- 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
Every code is explained in Errors.
curl -X DELETE "https://api.theorbits.app/v1/teams/my-team/projects/my-app/sandboxes/sbx_01jc8x6e4mq2v7r9y3t5b0zp8w" \
-H "Authorization: Bearer $ORBITS_TOKEN"Suspend a sandbox
Suspends the sandbox: CPU and memory are released, the disk is kept, and start resumes it with the work intact. The idle auto-stop does the same, so a timeout never loses work. state becomes stopped. Already stopped is a no-op 200.
Permissions: Owners, admins and members. Viewers get 403.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….Idempotency-KeystringrequiredA new value, such as a UUID, for each change. Resend with the same value and body to retry safely.
From 8 to 128 characters.
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.sandboxstringrequiredThe sandbox's name.
Response 200
The suspended sandbox.namestringrequiredruntimestringrequiredOne of
node22,python312,go123.sizestringrequiredsmall = 0.5 vCPU, 512 MB, 2 GB disk; large = 1 vCPU, 2 GB, 4 GB disk. Several pack onto one node.
One of
small,large.sourcestring or nullrequiredWhat was cloned (e.g. "storefront · main"); null for an empty machine.
statestringrequiredstoppedis suspended: the disk is kept andstartresumes it.One of
starting,running,stopped.started_atstringrequiredstopped_atstring or nullrequiredstarted_byFlagPersonrequiredShow 4 child fieldsHide child fields
idstringrequirednamestringrequiredemailstringrequiredavatar_urlstring or nullrequired
stop_afterintegerrequiredIdle minutes before it suspends itself.
One of
10,30,60,120.urlstringrequiredThe sandbox's preview URL (port 3000), reachable by team members only.
terminalarray of SandboxTerminalLinerequiredThe boot and run output so far; live output streams over the terminal WebSocket.
Show 2 child fieldsHide child fields
kindstringrequiredOne of
cmd,out,ok,err.textstringrequired
usageSandboxUsagerequiredShow 4 child fieldsHide child fields
cpuintegerrequiredPercent of the size's vCPU in use.
memory_gbnumberrequireddisk_gbnumberrequiredidle_minutesintegerrequiredMinutes since the last activity; drives the idle suspend.
Errors
- 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
Every code is explained in Errors.
curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/sandboxes/sbx_01jc8x6e4mq2v7r9y3t5b0zp8w/stop" \
-H "Authorization: Bearer $ORBITS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)"{
"name": "seed-test-data",
"runtime": "node22",
"size": "small",
"source": null,
"state": "starting",
"started_at": "2026-11-10T09:30:00Z",
"stopped_at": "2026-11-10T09:30:00Z",
"started_by": {
"id": "id",
"name": "my-app",
"email": "ada@example.com",
"avatar_url": "https://my-app.theorbits.app"
},
"stop_after": 10,
"url": "https://my-app.theorbits.app",
"terminal": [
{
"kind": "cmd",
"text": "text"
}
],
"usage": {
"cpu": 1,
"memory_gb": 1,
"disk_gb": 1,
"idle_minutes": 1
}
}Resume a sandbox
Resumes a stopped sandbox from its kept disk: state is starting, then running (poll GET .../sandboxes). Counts against the team's live limit, so this returns 409 when the team is already at SandboxPage.limit. Already running is a no-op 200.
Permissions: Owners, admins and members. Viewers get 403.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….Idempotency-KeystringrequiredA new value, such as a UUID, for each change. Resend with the same value and body to retry safely.
From 8 to 128 characters.
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.sandboxstringrequiredThe sandbox's name.
Response 200
The sandbox, starting.namestringrequiredruntimestringrequiredOne of
node22,python312,go123.sizestringrequiredsmall = 0.5 vCPU, 512 MB, 2 GB disk; large = 1 vCPU, 2 GB, 4 GB disk. Several pack onto one node.
One of
small,large.sourcestring or nullrequiredWhat was cloned (e.g. "storefront · main"); null for an empty machine.
statestringrequiredstoppedis suspended: the disk is kept andstartresumes it.One of
starting,running,stopped.started_atstringrequiredstopped_atstring or nullrequiredstarted_byFlagPersonrequiredShow 4 child fieldsHide child fields
idstringrequirednamestringrequiredemailstringrequiredavatar_urlstring or nullrequired
stop_afterintegerrequiredIdle minutes before it suspends itself.
One of
10,30,60,120.urlstringrequiredThe sandbox's preview URL (port 3000), reachable by team members only.
terminalarray of SandboxTerminalLinerequiredThe boot and run output so far; live output streams over the terminal WebSocket.
Show 2 child fieldsHide child fields
kindstringrequiredOne of
cmd,out,ok,err.textstringrequired
usageSandboxUsagerequiredShow 4 child fieldsHide child fields
cpuintegerrequiredPercent of the size's vCPU in use.
memory_gbnumberrequireddisk_gbnumberrequiredidle_minutesintegerrequiredMinutes since the last activity; drives the idle suspend.
Errors
- 402The team's plan doesn't include this (see
GET /v1/plans).codeisplan_required,required_planisproandfeaturenames what is missing; show the upgrade dialog. - 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
- 409The request conflicts with current state.
Every code is explained in Errors.
curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/sandboxes/sbx_01jc8x6e4mq2v7r9y3t5b0zp8w/start" \
-H "Authorization: Bearer $ORBITS_TOKEN" \
-H "Idempotency-Key: $(uuidgen)"{
"name": "seed-test-data",
"runtime": "node22",
"size": "small",
"source": null,
"state": "starting",
"started_at": "2026-11-10T09:30:00Z",
"stopped_at": "2026-11-10T09:30:00Z",
"started_by": {
"id": "id",
"name": "my-app",
"email": "ada@example.com",
"avatar_url": "https://my-app.theorbits.app"
},
"stop_after": 10,
"url": "https://my-app.theorbits.app",
"terminal": [
{
"kind": "cmd",
"text": "text"
}
],
"usage": {
"cpu": 1,
"memory_gb": 1,
"disk_gb": 1,
"idle_minutes": 1
}
}A ticket to open the sandbox's terminal
A WebSocket opened by a browser can't carry the session or a bearer, so the terminal (GET .../sandboxes/{sandbox}/terminal) takes this ticket in its ticket query parameter instead. The ticket (sbt_…) admits the caller to this one sandbox's terminal for 60 seconds: get one right before opening the socket. It is signed, not stored, so it can't be revoked before it expires. Takes no body. The answer is never cached and the call ignores Idempotency-Key, so every call mints a new ticket.
No plan check of its own: the sandbox must be running (else 409), and only Pro can start one.
Permissions: Any team member, viewers included. A session or a full API token may call it (a token limited to one project only for that project); a read token gets 403, because this is a POST. A non-member gets 404.
Headers
AuthorizationstringrequiredBearerand your API token:Bearer orb_live_….
Path parameters
teamstringrequiredTeam slug or
team_id.projectstringrequiredProject slug or
prj_id.sandboxstringrequiredThe sandbox's name.
Response 200
The ticket.ticketstringrequiredAdmits the caller to this sandbox's terminal for 60 seconds: the
ticketquery parameter ofGET .../sandboxes/{sandbox}/terminal.
Errors
- 401Missing or invalid credentials.
- 403Authenticated but not allowed in this team.
- 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
- 409The request conflicts with current state.
Every code is explained in Errors.
curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/sandboxes/sbx_01jc8x6e4mq2v7r9y3t5b0zp8w/terminal-ticket" \
-H "Authorization: Bearer $ORBITS_TOKEN"{
"ticket": "sbt_eyJzIjoic2J4XzEifQ.c2lnbmF0dXJl"
}