7.0 KiB
name: hanzo-api-sandbox description: The ONE compute primitive: a sandbox is a gVisor pod that runs somebody else's code, and every lifetime is the same object.
Hanzo Sandbox
Scope: The ONE compute primitive: a sandbox is a gVisor pod that runs somebody else's code, and every lifetime is the same…
Surface: 19 operations on /v1/sandboxes
Lines: ~157
Last Updated: 2026-08-20
Source: https://api.hanzo.ai/v1/openapi.json (x-app: sandboxes) — generated, do not hand-edit
When to Use This Skill
Activate this skill when:
- Running code you did not write — a model wrote it, or a user submitted it
- You need a filesystem, a terminal or a screen that outlives a single call
- Isolating a long-running job from the caller's process and from other tenants
- Driving a desktop: the screen and terminal websockets are on the same object
- Calling
/v1/sandboxes(19 operations)
Authentication
Every operation takes a Hanzo IAM bearer token. hanzo auth token prints the
active short-lived access token for the identity you are signed in as; the org
is carried in the token's claim, never in a path or a query parameter.
TOKEN=$(hanzo auth token)
curl -sS https://api.hanzo.ai/v1/... -H "Authorization: Bearer $TOKEN"
The document declares one scheme, bearer, at the top level: Authorization: Bearer <token>. X-Authorization and HTTP Basic carrying the token as the
password are accepted spellings of the same header; a browser presents the
session cookie instead. There is no product-specific key scheme.
Surface
| Family | Operations | Addresses under it |
|---|---|---|
/v1/sandboxes |
19 | end, lease, read, run, stop, write |
Operations
/v1/sandboxes
| Method | Path | Summary |
|---|---|---|
GET |
/v1/sandboxes |
The sandboxes this org holds |
POST |
/v1/sandboxes |
Lease a sandbox |
POST |
/v1/sandboxes/end |
End a sandbox and release it |
POST |
/v1/sandboxes/lease |
Lease a sandbox — a real computer — or resume one you hold |
POST |
/v1/sandboxes/read |
Read a file from a sandbox you hold |
POST |
/v1/sandboxes/run |
Run a command in a sandbox you hold and read its output |
POST |
/v1/sandboxes/stop |
Stop what a sandbox is running, and keep the sandbox |
POST |
/v1/sandboxes/write |
Write a file into a sandbox you hold |
DELETE |
/v1/sandboxes/{id} |
End a sandbox |
GET |
/v1/sandboxes/{id} |
One sandbox |
POST |
/v1/sandboxes/{id}/exec |
Run a command in a sandbox |
GET |
/v1/sandboxes/{id}/fs |
Read a file, or list a directory |
POST |
/v1/sandboxes/{id}/fs |
Write a file |
GET |
/v1/sandboxes/{id}/screen |
The screen, as a page |
POST |
/v1/sandboxes/{id}/screen/ticket |
Open a screen |
GET |
/v1/sandboxes/{id}/screen/ws |
The screen, as a socket |
GET |
/v1/sandboxes/{id}/terminal |
The terminal, as a page |
POST |
/v1/sandboxes/{id}/terminal/ticket |
Open a terminal |
GET |
/v1/sandboxes/{id}/terminal/ws |
The terminal, as a socket |
Example Calls
TOKEN=$(hanzo auth token)
Run a command in a sandbox you hold and read its output
curl -sS -X POST "https://api.hanzo.ai/v1/sandboxes/run" \
-H "Authorization: Bearer $TOKEN"
Body — RunIn:
| Field | Type | Required | What it is |
|---|---|---|---|
argv |
array of string | — | Argv is the program and its arguments, already split — the form no shell can misread. Give this or Command,… |
blind |
array of string | — | Blind is the set of secrets this command must never publish. |
command |
string | — | Command is a shell line, run by sh -c. Use it when a pipeline or a redirection is the point, and Argv when… |
dir |
string | — | Dir runs the command somewhere other than the sandbox's working directory, which Leased.Workdir names. |
id |
string | — | ID is the sandbox to run in, from an earlier lease. |
session |
string | — | Session is the live agent session this command narrates into: its output is appended there AS IT IS PRODUCED,… |
stdin |
string | — | Stdin is fed to the program on standard input. This is how bytes reach a file without being quoted into a… |
timeoutSec |
integer | — | TimeoutSec bounds this ONE command, so a wedged program holds the caller for its own timeout rather than for… |
Runs one command inside the caller's sandbox and answers its exit code, stdout and stderr. A non-zero exit is a successful call carrying a failed program, so it comes back as data and not as an error.
Lease a sandbox — a real computer — or resume one you hold
curl -sS -X POST "https://api.hanzo.ai/v1/sandboxes/lease" \
-H "Authorization: Bearer $TOKEN"
Body — LeaseIn:
| Field | Type | Required | What it is |
|---|---|---|---|
class |
string | — | Class is what KIND of computer to lease, and the set is closed: |
id |
string | — | ID names a sandbox to RESUME, and is the id an earlier lease answered with. Empty asks for a new one. A… |
project |
string | — | Project names the disk to attach, and is REQUIRED for every class but exec. |
runtime |
string | — | Runtime is the isolation boundary asked for: gvisor shares a filesystem and holds a project volume,… |
ttlSec |
integer | — | TTLSec bounds the lease in seconds. Unset takes the class default. Nothing runs forever, because a sandbox is… |
Leases the caller's sandbox, or returns the one it named if that lease is still running.
Stop what a sandbox is running, and keep the sandbox
curl -sS -X POST "https://api.hanzo.ai/v1/sandboxes/stop" \
-H "Authorization: Bearer $TOKEN"
Body — StopIn:
| Field | Type | Required | What it is |
|---|---|---|---|
id |
string | — |
Interrupts whatever the caller's sandbox is running and answers how many commands it ended. The sandbox stays leased — stop ends the WORK, end ends the RESOURCE — so whoever stopped a run can still read what it left behind.
Answers
Documented status codes across this product: 200 (5), 204 (1).
Composition
aiwrites the code, this runs it — the pairing behind every code-interpreter loopexecis the one-shot form of the same primitive: no lease, no id, no lifetime to managestorageands3hold what a sandbox produced after the sandbox is gonevisorrents the machines underneath; a sandbox is a pod, not a VM you manage
Related Skills
hanzo-api/agent.md— Autonomous agents for your org: define them, run them, keep every run.hanzo-api/task.md— Hanzo Tasks: durable workflows that survive a crash, with every run visible and…hanzo-api/tool.md— Everything your org can call, in one list: connector actions, functions, agents, skills…hanzo-api/automation.md— Workflows that run themselves, on a schedule or a webhook.hanzo-cloud-architecture/SKILL.md— how one binary serves all of thishanzo-api/INDEX.md— every Hanzo product, by domain
Last Updated: 2026-08-20 Generated from: https://api.hanzo.ai/v1/openapi.json