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

267 lines
22 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>hip-1325</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-1325.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/hip-1325">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/hip-1325.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-1325</h1><p class="lede">HIP-1325: Node — A Machine an Org Owns. Status Final. Hanzo architectural specification.</p><h1>HIP-1325: Node — A Machine an Org Owns</h1>
<h2>Abstract</h2>
<p><code>/v1/node</code> is an org&#x27;s own machines. An agent on someone&#x27;s machine dials in and holds a socket; the org lists what is connected and asks one of them to run a command, authorized once at the socket against the deployment&#x27;s own allowlist. It is implemented in <code>hanzoai/cloud</code> at <code>apps/node</code> (HIP-0106).</p>
<p>A node is not a bot. A bot is an agent bound to a machine and a bot RUN is a task the executor drives on a surface this platform operates (HIP-1107); a bot MACHINE is a box you RENT (HIP-1172). This is the machine you already own, connected. Three values, three names, three addresses.</p>
<h2>Motivation</h2>
<p>The machine half answered under the bot&#x27;s name. It was <code>/v1/bot/nodes</code> while one package served both planes, then <code>/v1/node</code> while the package was still called <code>bot</code> — an address not named for the app that answered it, which is the one line cloud&#x27;s <code>openapi/misfiled.txt</code> carried for it (HIP-0139 §5.1). The name has followed the address, and the two planes are two capabilities.</p>
<p>They were never one. HIP-0139 §7.2 permits a split along a store boundary and only there, and the boundary here was already drawn in the file layout: the node plane holds a presence map keyed by machine, and the run plane holds nothing at all because the executor holds it. Neither reads the other&#x27;s, neither has a symbol the other uses, and neither ever did. What kept them in one package was the shared word <code>bot</code>, which is exactly the coincidence HIP-0139 exists to refuse.</p>
<h2>Specification</h2>
<p>The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are to be interpreted as in RFC 2119.</p>
<h3>§1 The store</h3>
<p>No durable store.</p>
<p>A node is addressed by <code>(org, nodeID)</code> in an in-memory registry on the replica holding its socket — a lookup without an org cannot compile — and which replica holds which node is written to a shared presence map in Hanzo KV (<code>CLOUD_KV_URL</code>), because with more than one replica the socket lands on one pod and the invocations land on any.</p>
<p>The presence map is this capability&#x27;s alone. The run plane it split from opens no store, so there is nothing shared to divide and no reconciliation between them; that is the store boundary HIP-0139 §7.2 requires, and it predates the split.</p>
<h3>§2 The addresses</h3>
<p>Four route families under <code>/v1/node</code>. <code>GET /v1/node</code> is typed. Three are declared with prose beside their wire facts, held closed by this capability&#x27;s own projection gate — one gate per capability, because a ledger that spans two cannot say which of them a route belongs to:</p>
<p><code>GET /v1/node/connect</code> is a WebSocket upgrade — 101 and then a duplex frame stream for the life of the node, which no typed operation can declare. <code>POST /v1/node/{id}/invoke</code> refuses with a domain body a client switches on, identical for a pre-flight refusal and for the node&#x27;s own denial, and reads the caller&#x27;s device header, which no <code>In</code> field may carry: a caller that could name its own device could pre-approve its own privileged command. <code>POST /v1/node/peer/invoke</code> is the replica-to-replica forward — plain-text refusals, and a body bound a typed operation cannot see.</p>
<p>The peer hop is a machine call and not a public address: the public rule drops it (HIP-0135), so it reaches no generated client and no tool list.</p>
<h3>§3 Tenancy</h3>
<p>Every route takes its org from the gateway&#x27;s verdict — injected after IAM validation, after stripping any client copy (HIP-0026) — never from a body, query or path, because a caller that could name an org could attach a machine into someone else&#x27;s tenant, or run a command on one. Without a validated principal the request is refused rather than defaulted.</p>
<p>A node id belonging to another org MUST answer exactly like one that does not exist, so the surface is not an existence oracle, and an id is bounded before it is looked up — an oversize id is not a node this org has.</p>
<p>The one exception is the peer hop, whose org does arrive in a body: it is a machine call from another replica that derived the org from a validated header, and it authenticates with a shared token (<code>CLOUD_BOT_PEER_TOKEN</code>). Without that token the peer endpoint MUST serve nothing at all.</p>
<h3>§4 Authorization happens once, at the socket</h3>
<p>The registry runs the policy gate on the replica holding the node — the only one that knows what the node declared — so a locally-held node and one reached through a forward are authorized by the same code with the same session in hand. There MUST NOT be a second check at invoke time: a check in a place that sometimes has the session and sometimes does not is how two answers drift apart.</p>
<p>Everything a node self-reports — its capabilities, its commands, its platform — is shown and never load-bearing. What it may actually be asked to run is decided against the deployment&#x27;s allowlist, where a dangerous command is reachable only through an explicit allow and a deny wins over both. A connect carrying an Origin header is refused outright: a node is a daemon, and removing the browser category entirely is the gate.</p>
<h3>§5 Money</h3>
<p>Free, and said in those words: the plugin declares <code>Price: cloud.Free</code>. Nothing on this surface debits any plane.</p>
<h3>§6 Events and observability</h3>
<p>It publishes nothing on the bus, so a customer&#x27;s webhooks (HIP-1310) receive no <code>nodes.*</code> event. Beyond the request span every route gets, it emits structured log lines only.</p>
<h3>§7 Shutdown</h3>
<p>The presence-renew loop ends on graceful shutdown, which releases this replica&#x27;s claims on the way out so peers stop forwarding into a pod that is draining. The hook belongs to this capability&#x27;s binary and to no other: the run plane it split from has no loop and now declares none.</p>
<h3>§8 Stage</h3>
<p><code>ga</code>. The manifest row declares no stage, and absent is <code>ga</code> (HIP-0139 §8).</p>
<h3>§9 The name owes the singular sweep</h3>
<p>The row is <code>node</code>, and under the rule that now governs (HIP-0139) the canonical name is the singular: this capability&#x27;s row, package, plugin, floor key and tag become <code>node</code>. It is written plural here because that is what the manifest carries at the moment of writing, and a HIP whose <code>capability:</code> disagrees with the row describes a fleet nobody runs.</p>
<p>It is deliberately NOT renamed ahead of the sweep. Four siblings — <code>bot</code>, <code>campaign</code>, <code>link</code>, <code>network</code> — are in the identical state, and moving one of five leaves a mixed estate plus a collision with the slice that moves the rest. Nothing is broken while it waits: the derivation accepts <code>/v1/node</code> already, so both spellings answer and only the published spelling is pending.</p>
<h3>§10 Upstream</h3>
<p>It derives from no third-party OSS project. The socket wire is protocol version 3 of the <code>@hanzo/bot</code> TypeScript gateway, which Hanzo also maintains, implemented here frame-for-frame.</p>
<h2>Rationale</h2>
<p>The alternative rendezvous is the presence store&#x27;s own pub/sub, publishing invokes to the holding pod&#x27;s channel. It was rejected for its failure mode: a replica that died between the lookup and the publish costs the caller the whole timeout, where a direct peer forward fails fast and visibly.</p>
<p>The alternative to the split is the arrangement it replaces — one package, two planes, one address not named for its app and a line in the ratchet explaining it. Folding the other way, to <code>/v1/bot/nodes</code>, was the cheaper edit and the wrong one: it would file a machine under an agent&#x27;s name permanently, in nine projections, on the argument that they once shipped in the same binary.</p>
<h2>Security Considerations</h2>
<p>This capability&#x27;s wrong implementation is remote code execution on a customer&#x27;s machine — the commands include running processes and reading devices — so every control in §3 and §4 is about who can reach a node and with what.</p>
<p>The org from the gateway&#x27;s verdict closes cross-tenant attach and invoke. The Origin refusal closes a page riding a signed-in viewer&#x27;s session into registering a node. The allowlist closes a compromised cloud asking for a command the deployment never enabled. Correlation ids minted under the connection id mean a node can only ever answer calls placed on its own socket.</p>
<p>The peer token is the remaining credential, and an unauthenticated peer endpoint that took an org from a body would be a cross-tenant invoke primitive — which is why, absent the token, it serves nothing.</p>
<p>The split itself removes one hazard and creates none. The run plane&#x27;s relay is a greedy wildcard over <code>/v1/bot/runtime/*</code>; while both planes registered on one router, that wildcard and this capability&#x27;s static leaves were held apart by specificity alone. They are now in different binaries behind different prefixes, where neither can reach the other at all.</p>
<h2>References</h2>
<ul><li>HIP-0026 — Identity and Access Management</li><li>HIP-0106 — The Hanzo Plugin Contract</li><li>HIP-0135 — What Is Public</li><li>HIP-0139 — Capability</li><li>HIP-1107 — Bots — Runs on a Surface</li><li>HIP-1172 — visor — Compute You Rent</li><li>HIP-1310 — Webhooks — Outbound Delivery</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-1325.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>