Files
skills/public/hip-1146.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

246 lines
20 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>hip-1146</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="/hip-1146.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/hip-1146">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/hip-1146.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>hip-1146</h1><p class="lede">HIP-1146: Sandbox — A Lease on Isolated Compute. Status Final. Hanzo architectural specification.</p><h1>HIP-1146: Sandbox — A Lease on Isolated Compute</h1>
<h2>Abstract</h2>
<p><code>/v1/sandbox</code> is the ONE compute primitive: a sandbox is a gVisor pod that runs somebody else&#x27;s code, and every lifetime is the same object — a function invoke is a sandbox with a seconds-long lease, a code-exec call one with a session lease, an agentic coding run one with a project volume and a long lease. Not three subsystems, not three schedulers: one record, one pod spec, one way in (<code>apps/sandbox/sandbox.go:1-10</code>). The implementation is <code>hanzoai/cloud</code> <code>apps/sandbox</code> (the manifest and plugin name the capability <code>sandbox</code>; the package keeps the singular noun).</p>
<h2>Motivation</h2>
<p>Running submitted code is one problem however it arrives, and the platform built it three times before it built it once: exec&#x27;s predecessor shipped an in-pod HTTP daemon with eleven endpoints, a shared pool-wide API key and a pod-IP address book, all deleted because Kubernetes already had the channel (<code>apps/sandbox/sandbox.go:32-38</code>). What differs between a function run and a coding run is <code>ttlSec</code> and whether a volume is attached — a class row, not a subsystem.</p>
<h2>Specification</h2>
<p>The key words MUST, MUST NOT and SHOULD are to be interpreted as in RFC 2119.</p>
<h3>The store</h3>
<p>One SQLite file per org, <code>{DataDir}/orgs/{org}/sandbox.db</code> via <code>cloud.OrgDB</code>: the org&#x27;s sandbox registry. Isolation is PHYSICAL — a different org is a different file — with the org column kept as defence in depth (<code>apps/sandbox/store.go:57-61</code>). The pods themselves are cluster state, bound by the <code>Bound</code> namespace+label pair whose constructor refuses <code>kube-system</code>, <code>default</code>, <code>hanzo</code> and every <code>kube-*</code> namespace before a client even exists (<code>apps/sandbox/bound.go</code>).</p>
<h3>Addresses</h3>
<p>Nineteen operations under <code>/v1/sandbox</code> (<code>apps/sandbox/sandbox.go:241-296</code>). Thirteen are raw routes with prose declared beside each (<code>openapi.Describe</code>): the collection and member CRUD, <code>POST /{id}/exec</code>, <code>GET|POST /{id}/fs</code>, and the ticketed terminal and screen trios — the terminal is a WebSocket PTY and the screen a live display, wires no typed op can answer. Six ARE typed ops, registered from the same handlers the internal plane serves (<code>lease</code>, <code>run</code>, <code>read</code>, <code>write</code>, <code>stop</code>, <code>end</code>), so an agent at the fleet&#x27;s MCP endpoint can name them; <code>stop</code> ends the WORK and <code>end</code> ends the RESOURCE, two verbs because a run that went wrong is one somebody still wants to look at.</p>
<p>There MUST be exactly one way into a sandbox — the Kubernetes exec subresource; fs read/list/write are <code>cat</code>, <code>ls</code> and <code>tee</code> over that channel, never a second one. Nothing runs in this package: no <code>os/exec</code>, ever (<code>apps/sandbox/sandbox.go:47-50</code>).</p>
<h3>Addressing and lifetime</h3>
<p>A sandbox is addressed by POD NAME through the apiserver, NEVER by IP: a pod that dies on its own never runs a release path, and a row holding a stale IP is served by whichever stranger the CNI handed that address to (<code>apps/sandbox/sandbox.go:38-46</code>). Names are minted per sandbox and never reused. There is no pool: a sandbox is created for a lease and deleted at its end; the reaper (every minute) ends expired leases and sleeps sandboxes idle past an hour, and its orphan sweep deletes by name+UID precondition only what carries the sandbox label inside the bound namespace, aborting whole when any store is unreadable.</p>
<h3>Tenancy and credentials</h3>
<p>The org is <code>principal.Org</code>, refused when absent; it selects the per-org file and every pod&#x27;s ownership. No caller credential reaches a sandbox from the pod spec — a spec value is a value in etcd — and the ONE credential a lease is handed arrives over the exec channel: a short-lived IAM token EXCHANGED (RFC 8693) for the token the caller presented, acting as the <code>hanzo-sandbox</code> client which deliberately lacks the admin-mint capability, expiring with the lease and carrying no refresh token (<code>apps/sandbox/cred.go:1-28</code>). The pod carries no ServiceAccount token at all.</p>
<h3>Money</h3>
<p>Metered at a price of zero: <code>plugin/sandbox/main.go</code> declares <code>Price: cloud.Metered</code> and <code>sandbox</code> is in the <code>meteredApps</code> standing list (<code>spend.go:311</code>). A lease is gated and debited through the shared <code>cloud.ResourceMeter</code> under kind <code>sandbox</code>, but every class fee defaults to 0 (<code>SANDBOX_FEE_CENTS[_EXEC|_DEV|_DESKTOP]</code>), deliberately not to the platform&#x27;s $1.00 default: shipping the meter must not also ship a price, and turning one on is a values change (<code>apps/sandbox/api.go:128-135</code>). Bursts are bounded independently of price: an org&#x27;s live exec-class sandboxes are capped, refused with 429 because the correct caller response is to wait.</p>
<h3>Events, telemetry, stage, upstream</h3>
<p>It publishes nothing to the bus, so a customer&#x27;s webhooks receive nothing from it; beyond the request span it emits log lines only. Stage <code>ga</code>: the manifest row (<code>manifest/apps.go:368</code>) declares no stage, and absent means <code>ga</code>. Upstream: <code>k8s.io/client-go</code> (Apache-2.0) is the imported client; gVisor&#x27;s <code>runsc</code> and the Kata runtimes (Apache-2.0) are the isolation boundaries the pod spec selects by RuntimeClass, run by the cluster, embedded by nothing here.</p>
<h2>Rationale</h2>
<p>One primitive with a class row, instead of per-product runtimes, is the whole design: every fact a sandbox must get right — tenant file, pod addressing, lease, credential ceiling, reaper — is written once and inherited by function invokes, code exec and coding runs alike, where three subsystems were three places to get one of them half-right. The closed <code>classes</code> table exists because its predecessor — three tables in two files — let a new class be half-added silently: missing from the TTL map it was reaped before its caller finished reading the reply (<code>apps/sandbox/sandbox.go:92-101</code>).</p>
<h2>Security Considerations</h2>
<p>This capability&#x27;s job is running hostile code, so the attacker is assumed to be inside the pod. What the wrong implementation hands them: a platform credential (closed by the exchange ceiling — the acting client cannot mint for reserved orgs, so even an operator&#x27;s lease starts unprivileged); another tenant&#x27;s pod (a stale IP in a row — closed by name-only addressing; a recycled name — closed by UID preconditions on delete); or the cluster itself (a sweep with a hurried selector once deleted kube-system DaemonSet pods, which is why the namespace+label bound is a type no call site can construct half of). The per-org file plus the org column is the read boundary; the missing ServiceAccount token is what makes the pod&#x27;s inside worth less than its outside.</p>
<h2>References</h2>
<ul><li>HIP-0026 — Identity and Access Management</li><li>HIP-0106 — The Hanzo Plugin Contract</li><li>HIP-0139 — Capability</li><li>RFC 8693 — OAuth 2.0 Token Exchange</li></ul>
<h2>Copyright</h2>
<p>Released under CC0 1.0 Universal Public Domain Dedication.</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="/hip-1146.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>