Files
skills/public/hanzo-api-sandbox.md

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

  • 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
  • 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