Files
skills/public/hanzo-api-sandbox.html
zeekayandHanzo Dev 9e10c1c10e Each llms index points at the other two
hanzoskills.com/llms.txt now opens with the install line, the API
reference index and the company index, so an agent that lands on any
one of the three can find the rest.

robots.txt claimed 537 documents while llms.txt counts 920. The number
is gone from robots.txt; llms.txt derives it.

public/ is regenerated from scripts/site.py, which it had fallen
behind: the copy-prompt menu and agent bar were in the generator and
not in the committed pages. tests/site.mjs passes against the result.

Co-authored-by: Hanzo Dev <[email protected]>
2026-09-11 00:27:59 -07:00

261 lines
21 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>hanzo-api-sandbox</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="alternate" type="text/markdown" href="/hanzo-api-sandbox.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/hanzo-api-sandbox">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/hanzo-api-sandbox.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>hanzo-api-sandbox</h1><p class="lede">The ONE compute primitive: a sandbox is a gVisor pod that runs somebody else&#x27;s code, and every lifetime is the same object.</p><h1>Hanzo Sandbox</h1>
<p><strong>Scope</strong>: The ONE compute primitive: a sandbox is a gVisor pod that runs somebody else&#x27;s code, and every lifetime is the same… <strong>Surface</strong>: 19 operations on <code>/v1/sandboxes</code> <strong>Lines</strong>: ~157 <strong>Last Updated</strong>: 2026-08-20 <strong>Source</strong>: https://api.hanzo.ai/v1/openapi.json (<code>x-app: sandboxes</code>) — generated, do not hand-edit</p>
<h2>When to Use This Skill</h2>
<p>Activate this skill when:</p>
<ul><li>Running code you did not write — a model wrote it, or a user submitted it</li><li>You need a filesystem, a terminal or a screen that outlives a single call</li><li>Isolating a long-running job from the caller&#x27;s process and from other tenants</li><li>Driving a desktop: the screen and terminal websockets are on the same object</li><li>Calling <code>/v1/sandboxes</code> (19 operations)</li></ul>
<h2>Authentication</h2>
<p>Every operation takes a Hanzo IAM bearer token. <code>hanzo auth token</code> prints the active short-lived access token for the identity you are signed in as; the org is carried in the token&#x27;s claim, never in a path or a query parameter.</p>
<pre><code class="lang-bash">TOKEN=$(hanzo auth token)
curl -sS https://api.hanzo.ai/v1/... -H &quot;Authorization: Bearer $TOKEN&quot;</code></pre>
<p>The document declares one scheme, <code>bearer</code>, at the top level: <code>Authorization: Bearer &lt;token&gt;</code>. <code>X-Authorization</code> 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.</p>
<h2>Surface</h2>
<p>| Family | Operations | Addresses under it | |---|---|---| | <code>/v1/sandboxes</code> | 19 | <code>end</code>, <code>lease</code>, <code>read</code>, <code>run</code>, <code>stop</code>, <code>write</code> |</p>
<h2>Operations</h2>
<h3><code>/v1/sandboxes</code></h3>
<p>| Method | Path | Summary | |---|---|---| | <code>GET</code> | <code>/v1/sandboxes</code> | The sandboxes this org holds | | <code>POST</code> | <code>/v1/sandboxes</code> | Lease a sandbox | | <code>POST</code> | <code>/v1/sandboxes/end</code> | End a sandbox and release it | | <code>POST</code> | <code>/v1/sandboxes/lease</code> | Lease a sandbox — a real computer — or resume one you hold | | <code>POST</code> | <code>/v1/sandboxes/read</code> | Read a file from a sandbox you hold | | <code>POST</code> | <code>/v1/sandboxes/run</code> | Run a command in a sandbox you hold and read its output | | <code>POST</code> | <code>/v1/sandboxes/stop</code> | Stop what a sandbox is running, and keep the sandbox | | <code>POST</code> | <code>/v1/sandboxes/write</code> | Write a file into a sandbox you hold | | <code>DELETE</code> | <code>/v1/sandboxes/{id}</code> | End a sandbox | | <code>GET</code> | <code>/v1/sandboxes/{id}</code> | One sandbox | | <code>POST</code> | <code>/v1/sandboxes/{id}/exec</code> | Run a command in a sandbox | | <code>GET</code> | <code>/v1/sandboxes/{id}/fs</code> | Read a file, or list a directory | | <code>POST</code> | <code>/v1/sandboxes/{id}/fs</code> | Write a file | | <code>GET</code> | <code>/v1/sandboxes/{id}/screen</code> | The screen, as a page | | <code>POST</code> | <code>/v1/sandboxes/{id}/screen/ticket</code> | Open a screen | | <code>GET</code> | <code>/v1/sandboxes/{id}/screen/ws</code> | The screen, as a socket | | <code>GET</code> | <code>/v1/sandboxes/{id}/terminal</code> | The terminal, as a page | | <code>POST</code> | <code>/v1/sandboxes/{id}/terminal/ticket</code> | Open a terminal | | <code>GET</code> | <code>/v1/sandboxes/{id}/terminal/ws</code> | The terminal, as a socket |</p>
<h2>Example Calls</h2>
<pre><code class="lang-bash">TOKEN=$(hanzo auth token)</code></pre>
<p><strong>Run a command in a sandbox you hold and read its output</strong></p>
<pre><code class="lang-bash">curl -sS -X POST &quot;https://api.hanzo.ai/v1/sandboxes/run&quot; \
-H &quot;Authorization: Bearer $TOKEN&quot;</code></pre>
<p>Body — <code>RunIn</code>:</p>
<p>| Field | Type | Required | What it is | |---|---|---|---| | <code>argv</code> | array of string | — | Argv is the program and its arguments, already split — the form no shell can misread. Give this or Command,… | | <code>blind</code> | array of string | — | Blind is the set of secrets this command must never publish. | | <code>command</code> | string | — | Command is a shell line, run by <code>sh -c</code>. Use it when a pipeline or a redirection is the point, and Argv when… | | <code>dir</code> | string | — | Dir runs the command somewhere other than the sandbox&#x27;s working directory, which Leased.Workdir names. | | <code>id</code> | string | — | ID is the sandbox to run in, from an earlier lease. | | <code>session</code> | string | — | Session is the live agent session this command narrates into: its output is appended there AS IT IS PRODUCED,… | | <code>stdin</code> | string | — | Stdin is fed to the program on standard input. This is how bytes reach a file without being quoted into a… | | <code>timeoutSec</code> | integer | — | TimeoutSec bounds this ONE command, so a wedged program holds the caller for its own timeout rather than for… |</p>
<p>Runs one command inside the caller&#x27;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.</p>
<p><strong>Lease a sandbox — a real computer — or resume one you hold</strong></p>
<pre><code class="lang-bash">curl -sS -X POST &quot;https://api.hanzo.ai/v1/sandboxes/lease&quot; \
-H &quot;Authorization: Bearer $TOKEN&quot;</code></pre>
<p>Body — <code>LeaseIn</code>:</p>
<p>| Field | Type | Required | What it is | |---|---|---|---| | <code>class</code> | string | — | Class is what KIND of computer to lease, and the set is closed: | | <code>id</code> | string | — | ID names a sandbox to RESUME, and is the id an earlier lease answered with. Empty asks for a new one. A… | | <code>project</code> | string | — | Project names the disk to attach, and is REQUIRED for every class but <code>exec</code>. | | <code>runtime</code> | string | — | Runtime is the isolation boundary asked for: <code>gvisor</code> shares a filesystem and holds a project volume,… | | <code>ttlSec</code> | integer | — | TTLSec bounds the lease in seconds. Unset takes the class default. Nothing runs forever, because a sandbox is… |</p>
<p>Leases the caller&#x27;s sandbox, or returns the one it named if that lease is still running.</p>
<p><strong>Stop what a sandbox is running, and keep the sandbox</strong></p>
<pre><code class="lang-bash">curl -sS -X POST &quot;https://api.hanzo.ai/v1/sandboxes/stop&quot; \
-H &quot;Authorization: Bearer $TOKEN&quot;</code></pre>
<p>Body — <code>StopIn</code>:</p>
<p>| Field | Type | Required | What it is | |---|---|---|---| | <code>id</code> | string | — | |</p>
<p>Interrupts whatever the caller&#x27;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.</p>
<h2>Answers</h2>
<p>Documented status codes across this product: <code>200</code> (5), <code>204</code> (1).</p>
<h2>Composition</h2>
<ul><li><code>ai</code> writes the code, this runs it — the pairing behind every code-interpreter loop</li><li><code>exec</code> is the one-shot form of the same primitive: no lease, no id, no lifetime to manage</li><li><code>storage</code> and <code>s3</code> hold what a sandbox produced after the sandbox is gone</li><li><code>visor</code> rents the machines underneath; a sandbox is a pod, not a VM you manage</li></ul>
<h2>Related Skills</h2>
<ul><li><code>hanzo-api/agent.md</code> — Autonomous agents for your org: define them, run them, keep every run.</li><li><code>hanzo-api/task.md</code> — Hanzo Tasks: durable workflows that survive a crash, with every run visible and…</li><li><code>hanzo-api/tool.md</code> — Everything your org can call, in one list: connector actions, functions, agents, skills…</li><li><code>hanzo-api/automation.md</code> — Workflows that run themselves, on a schedule or a webhook.</li><li><code>hanzo-cloud-architecture/SKILL.md</code> — how one binary serves all of this</li><li><code>hanzo-api/INDEX.md</code> — every Hanzo product, by domain</li></ul>
<hr>
<p><strong>Last Updated</strong>: 2026-08-20 <strong>Generated from</strong>: https://api.hanzo.ai/v1/openapi.json</p>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/hanzo-api-sandbox.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>