Files
skills/public/hanzo-cloud.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

295 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-cloud</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-cloud.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/hanzo-cloud">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/hanzo-cloud.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-cloud</h1><p class="lede">hanzoai/cloud is ONE Go binary that embeds every Hanzo-native subsystem — IAM, KMS, o11y, tasks, notify, pubsub, kafka, console, ai (the former LLM control plane), and the rest — behind a single plugin registry.</p><h1>Hanzo Cloud - The Unified One-Binary Cloud</h1>
<p><strong>Category</strong>: Hanzo Ecosystem <strong>Canonical spec</strong>: HIP-0106 (one binary), HIP-0114 (ZAP), HIP-0116 (plugin VMs), HIP-0117 (deploy modes) <strong>Related Skills</strong>: <code>hanzo-cloud-architecture/SKILL.md</code> (read first), <code>hanzo/hanzo-zap.md</code>, <code>hanzo/hanzo-gateway.md</code>, <code>hanzo/hanzo-console.md</code>, <code>hanzo/hanzo-iam.md</code></p>
<h2>Overview</h2>
<p><code>hanzoai/cloud</code> is <strong>ONE Go binary</strong> that embeds every Hanzo-native subsystem — IAM, KMS, o11y, tasks, notify, pubsub, kafka, console, ai (the former LLM control plane), and the rest — behind a single plugin registry. It is built on <strong>zip</strong> (<code>github.com/hanzoai/zip</code>, the ZAP-native high-performance server): a <strong>977-LOC shim</strong> plus <code>cloud.Register(name, order, mount)</code> and <strong>74,561 LOC of plugins</strong> under <code>clients/*</code> (76:1 plugin:core). The console SPA is <code>go:embed</code>&#x27;d (real <code>hanzoai/console</code> static build; 303.6 MiB one-binary; fail-hard Dockerfile). The same artifact powers <code>api.hanzo.ai</code>, <code>api.lux.cloud</code>, <code>api.zoo.cloud</code>, and every white-label surface — brand, enabled subsystems, and tenant scope are deployment configuration.</p>
<p><strong>Naming note</strong>: the former &quot;AI provider management platform&quot; content that used to live at <code>hanzoai/cloud</code> was renamed to <code>hanzoai/ai</code> and mounts as the <code>ai</code> subsystem inside this binary. White-label fork target is <code>hanzoai/cloud</code>.</p>
<h2>When to use</h2>
<ul><li>Working on any embedded subsystem (<code>clients/*</code>) or the cloud core</li><li>Standing up a full Hanzo cloud locally (<code>cloud serve</code> — no Kubernetes)</li><li>Deploying or white-labeling a cloud surface</li><li>Managing AI providers/keys (the <code>ai</code> subsystem + gateway HIP-0004)</li><li>Wiring per-product metered usage and 402 balance-gating via console</li></ul>
<h2>Hard requirements</h2>
<ol><li><strong>ZAP only</strong> (HIP-0114): zero gRPC, zero protobuf in Hanzo code. The pb</li></ol>
<p> boundary is <code>zap2pb</code>/<code>pb2zap</code>/<code>zapc</code> at the OTel edge exclusively.</p>
<ol><li><strong>zip is the one server framework</strong> — no Beego, no Gin, no echo, no</li></ol>
<p> second framework.</p>
<ol><li><strong>SQLite-primary per-tenant</strong> storage; PostgreSQL only for production</li></ol>
<p> multi-instance. Never default to PostgreSQL for local dev.</p>
<ol><li><strong>Subsystems fail closed</strong>: an embed without its required config refuses</li></ol>
<p> to mount. Disabled-by-default in production; deployments enable explicitly via <code>cfg.Enable</code> (flags/env).</p>
<ol><li><strong>IAM identity from hanzo.id</strong>; org from the JWT <code>owner</code> claim; all data</li></ol>
<p> scoped to org.</p>
<h2>Quick reference</h2>
<p>| Item | Value | |------|-------| | Repo | <code>github.com/hanzoai/cloud</code> (<code>~/work/hanzo/cloud</code>) | | Entrypoints | <code>cmd/cloud</code> (full surface), <code>cmd/hanzo</code> (subcommand dispatcher) | | Registry | <code>cloud.Register</code> / <code>cloud.RegisterWithShutdown</code> (<code>build.go</code>) | | Subsystem set | <code>subsystems</code> bundle (one source of truth, blank-imported) | | Plugins | <code>clients/*</code> (admin, ai, billing, console, iamsvc, kmssvc, kafka, notify, o11y, tasksvc, ...) | | Server | <code>github.com/hanzoai/zip</code> — ZAP primary + HTTP extra, one <code>Listen</code> | | Console | <code>go:embed</code> SPA (<code>webui.go</code>, <code>clients/console</code>) | | Helm chart | <code>cloud/helm/cloud</code> | | Image | <code>ghcr.io/hanzoai/cloud</code> (Gitea Actions CI, GH mirror) | | API surface | <code>api.hanzo.ai</code> (<code>/v1/...</code>, never <code>/api/</code> prefixes) | | Dashboard | <code>console.hanzo.ai</code> (usage metering, 402 balance-gating) |</p>
<h2>Architecture</h2>
<pre><code> ONE binary: cloud
┌───────────────────────────────────────────────────┐
│ zip (ZAP-native server, Fiber v3/fasthttp) │
│ cloud core: 977-LOC shim + Register() registry │
├───────────────────────────────────────────────────┤
│ clients/* plugins (74,561 LOC) │
│ iamsvc │ kmssvc │ o11y │ tasksvc │ notify │
│ pubsub │ kafka │ console (embedded SPA) │ ai │
│ billing │ admin │ analytics │ ... │
├───────────────────────────────────────────────────┤
│ SQLite per-tenant │ datastore (ClickHouse) │
│ Quasar + zapdb (replication — no ZK/raft/etcd) │
└───────────────────────────────────────────────────┘
transport everywhere: ZAP (HIP-0114)</code></pre>
<p>Each <code>hanzoai/&lt;repo&gt;</code> service still builds standalone; inside cloud it is a subsystem, and (HIP-0116, staged) the same code runs as an out-of-process <strong>plugin VM</strong> dialed over ZAP and distributed via <code>luxfi/lpm</code>. In-process vs out-of-process is deployment topology, not architecture.</p>
<h2>Adding a subsystem</h2>
<pre><code class="lang-go">// clients/example/example.go
package example
import &quot;github.com/hanzoai/cloud&quot;
func init() {
cloud.Register(&quot;example&quot;, 50, mount) // name, mount order, mount func
}
func mount(app cloud.App, cfg cloud.Config) error {
if cfg.ExampleDSN == &quot;&quot; {
return cloud.ErrNotConfigured // fail closed, never degrade silently
}
app.Get(&quot;/v1/example/:id&quot;, handler) // /v1/, never /api/
return nil
}</code></pre>
<p>Then add it to the <code>subsystems</code> bundle — the ONE place the set is defined.</p>
<h2>Running</h2>
<pre><code class="lang-bash"># The whole cloud on a laptop — no Kubernetes, SQLite per-tenant (HIP-0117 mode 1)
cloud serve
# Bootstrap a k3s HA cluster + operator + services.hanzo.ai CRs (mode 2, staged)
cloud cluster init
# BYO Kubernetes (mode 3)
helm install cloud ./helm/cloud</code></pre>
<h2>API key usage (the <code>ai</code> subsystem + gateway)</h2>
<pre><code class="lang-bash">export HANZO_API_KEY=sk-...
curl https://api.hanzo.ai/v1/chat/completions \
-H &quot;Authorization: Bearer ${HANZO_API_KEY}&quot; \
-H &quot;Content-Type: application/json&quot; \
-d &#x27;{&quot;model&quot;: &quot;zen-70b&quot;, &quot;messages&quot;: [{&quot;role&quot;: &quot;user&quot;, &quot;content&quot;: &quot;Hello&quot;}]}&#x27;</code></pre>
<p>The gateway (HIP-0004) is the unified AI provider interface — 100+ providers, BYO keys. Usage is metered per product in console; exhausted balance returns <strong>402</strong> at the gate.</p>
<h2>Troubleshooting</h2>
<p>| Issue | Cause | Solution | |-------|-------|----------| | Subsystem missing from a deploy | Not in <code>cfg.Enable</code> | Enable it explicitly; embeds are disabled-by-default | | Subsystem refuses to mount | Required config absent | That is fail-closed working as designed — supply the config | | Console SPA 404 | Binary built without embed | Rebuild via CI; the Dockerfile fails hard when the SPA is missing | | Postgres in local dev | Wrong default | <code>cloud serve</code> uses per-tenant SQLite; do not add Postgres | | gRPC/proto imports in review | Stale pattern | Rewrite on ZAP types; pb only at the OTel edge (<code>zap2pb</code>) |</p>
<h2>Related Skills</h2>
<ul><li><code>hanzo-cloud-architecture/SKILL.md</code> — the canonical architecture skill</li><li><code>hanzo/hanzo-zap.md</code> — ZAP transport and MCP mapping</li><li><code>hanzo/hanzo-gateway.md</code> — HIP-0004 AI gateway at api.hanzo.ai</li><li><code>hanzo/hanzo-console.md</code> — dashboard, metering, LLM observability</li><li><code>hanzo/hanzo-iam.md</code> — identity (embedded <code>iamsvc</code>)</li></ul>
<hr>
<p><strong>Category</strong>: Hanzo Ecosystem <strong>Related</strong>: cloud, one-binary, zip, zap, plugins, subsystems, white-label, console <strong>Prerequisites</strong>: Go, the hanzo-cloud-architecture skill</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-cloud.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>