hanzo-api-sandbox

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

ai writes the code, this runs it — the pairing behind every code-interpreter loop
exec is the one-shot form of the same primitive: no lease, no id, no lifetime to manage
storage and s3 hold what a sandbox produced after the sandbox is gone
visor rents 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 this
hanzo-api/INDEX.md — every Hanzo product, by domain

Last Updated: 2026-08-20 Generated from: https://api.hanzo.ai/v1/openapi.json