Files
skills/public/hanzo-cloud-architecture.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
23 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-architecture</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-architecture.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/hanzo-cloud-architecture">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/hanzo-cloud-architecture.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-architecture</h1><p class="lede">The canonical Hanzo Cloud architecture — one Go binary on zip, ZAP-only transport, plugin registry, embedded console, three deployment modes. Read this before touching any hanzoai service.</p><h1>Hanzo Cloud Architecture — One Binary, ZAP-Native, Plugin-Composed</h1>
<p><strong>Category</strong>: Hanzo Ecosystem <strong>Canonical spec</strong>: HIP-0106 (one binary), HIP-0114 (ZAP transport), HIP-0116 (plugin/VM model), HIP-0117 (cloud-in-a-box), HIP-0004 (AI gateway) — <code>github.com/hanzoai/hips</code> <strong>Related Skills</strong>: <code>hanzo/hanzo-cloud.md</code>, <code>hanzo/hanzo-zap.md</code>, <code>hanzo/hanzo-gateway.md</code>, <code>hanzo/hanzo-o11y.md</code>, luxfi/skills <code>lux-zap-substrate</code></p>
<h2>When to Use This Skill</h2>
<ul><li>Working anywhere in <code>hanzoai/cloud</code> or any service it embeds (IAM, KMS, o11y, tasks, notify, pubsub, kafka, console, ai, ...)</li><li>Adding a new Hanzo service or subsystem</li><li>Choosing a transport, RPC layer, or storage backend for Hanzo code</li><li>Deploying Hanzo Cloud (laptop, k3s bootstrap, or BYO Kubernetes)</li><li>Reading any older doc that mentions multi-pod services or gRPC — this skill is the current truth</li></ul>
<h2>The Architecture in One Paragraph</h2>
<p><code>hanzoai/cloud</code> is ONE Go binary that embeds every Hanzo-native subsystem — IAM, KMS, o11y, tasks, notify, pubsub, kafka, console, ai, and the rest — as packages behind a single plugin registry. The core is a <strong>977-LOC shim</strong> on <strong>zip</strong> (<code>github.com/hanzoai/zip</code>, the ZAP-native high-performance server, Fiber v3/fasthttp, HIP-0105); the subsystems are <strong>74,561 LOC of plugins</strong> under <code>clients/*</code> — a 76:1 plugin-to-core ratio. Transport is <strong>ZAP and nothing else</strong> (HIP-0114): zero gRPC, zero protobuf in Hanzo code. The same artifact powers <code>api.hanzo.ai</code> and every white-label resold cloud surface; brand, enabled subsystems, and tenant scope are deployment configuration.</p>
<h2>Status: shipped vs decided</h2>
<p>| Piece | Status | |-------|--------| | One binary (<code>hanzoai/cloud</code>, subsystems embedded) | <strong>SHIPPED</strong> | | ZAP-only transport, zero gRPC/protobuf in Hanzo code | <strong>SHIPPED</strong> | | zip as the one server framework | <strong>SHIPPED</strong> | | Console SPA <code>go:embed</code>&#x27;d (303.6 MiB one-binary, fail-hard Dockerfile) | <strong>SHIPPED</strong> | | console.hanzo.ai per-product metered usage + 402 balance-gating | <strong>SHIPPED</strong> | | <code>helm install</code> (charts at <code>cloud/helm/cloud</code>) | <strong>SHIPPED</strong> | | Plugin <strong>VM</strong> formalization (out-of-process VMs via lpm, HIP-0116) | <strong>DECIDED</strong> (HIP Draft, staged) | | <code>cloud cluster init</code> k3s bootstrap (HIP-0117 mode 2) | <strong>DECIDED</strong> (HIP Draft, staged) | | Visor per-tenant cross-provider autoscaling | <strong>DECIDED</strong> (staged) |</p>
<h2>Core Concepts</h2>
<h3>1. The plugin registry (<code>cloud.Register</code>)</h3>
<p>Every subsystem registers into the cloud registry via <code>init()</code>:</p>
<pre><code class="lang-go">// build.go — the whole extension API
func Register(name string, order int, mount MountFunc)
func RegisterWithShutdown(name string, order int, mount MountFunc, shutdown ShutdownFunc)</code></pre>
<ul><li>Subsystems live in <code>clients/&lt;name&gt;/</code> (e.g. <code>clients/kmssvc</code>, <code>clients/o11y</code>,</li></ul>
<p> <code>clients/console</code>, <code>clients/tasksvc</code>, <code>clients/notify</code>, <code>clients/kafka</code>).</p>
<ul><li>The subsystem set is defined ONCE in the <code>subsystems</code> bundle; <code>cmd/cloud</code></li></ul>
<p> and <code>cmd/hanzo</code> blank-import it. <code>cloud.Serve(nil)</code> honors <code>cfg.Enable</code> from flags/env.</p>
<ul><li><code>cmd/cloud</code> is the full-surface entrypoint; production deployments name</li></ul>
<p> their subsystem set explicitly. Embedded subsystems ship <strong>disabled-by-default and fail closed</strong>: a subsystem without its required config refuses to mount rather than degrading silently.</p>
<h3>2. ZAP-only transport (HIP-0114)</h3>
<ul><li>ZERO gRPC and ZERO protobuf anywhere in Hanzo code. The transport between</li></ul>
<p> subsystems, plugins, and services is ZAP — zero-copy, ZAP-typed Go interfaces in-process, ZAP RPC over the wire when split.</p>
<ul><li>The ONLY protobuf in the stack is <code>zap2pb</code> (<code>~/work/zap/zap2pb</code>, ~30 LOC)</li></ul>
<p> at the OTel interop edge (OTLP/OpAMP). <code>pb2zap</code> / <code>zap2pb</code> / <code>zapc</code> handle the pb↔zap boundary; services hold only ZAP types.</p>
<ul><li>zip serves ZAP as the primary listener with HTTP as an extra:</li></ul>
<p> <code>app.Listen(&quot;:9653&quot;, &quot;http://:8080&quot;)</code>.</p>
<pre><code class="lang-go">// ❌ NEVER in Hanzo code
import &quot;google.golang.org/grpc&quot; // no gRPC
import &quot;google.golang.org/protobuf&quot; // no protobuf
// ✅ The one server framework, ZAP-typed handlers
import &quot;github.com/hanzoai/zip&quot;</code></pre>
<h3>3. Storage and consensus</h3>
<ul><li><strong>SQLite-primary, per-tenant</strong> — the default store for every subsystem.</li></ul>
<p> PostgreSQL only for production multi-instance needs; never default to it for local dev.</p>
<ul><li><strong>datastore</strong> (ClickHouse) is the ONE non-Go exception — telemetry and</li></ul>
<p> analytics columns.</p>
<ul><li><strong>Consensus/replication</strong> = Lux Quasar (<code>luxfi/consensus</code>) + <code>luxfi/zapdb</code>.</li></ul>
<p> NO ZooKeeper, NO raft libraries, NO etcd anywhere in the stack.</p>
<h3>4. Plugin/VM model (HIP-0116 — decided, staged)</h3>
<p>Every <code>hanzoai/&lt;repo&gt;</code> service builds BOTH ways from one codebase:</p>
<ol><li><strong>Standalone binary</strong> — its own repo, its own release.</li><li><strong>Plugin VM</strong> for the cloud host — the <code>luxfi/node</code> VM-host model: an</li></ol>
<p> independently-built binary the host supervises and dials <strong>over ZAP</strong>. Distributed and installed via <code>luxfi/lpm</code>.</p>
<p>NOT build tags. NOT gRPC. NOT dlopen. A plugin VM is simply a subsystem that lives in another process; in-process and out-of-process resolve through the same ZAP-typed contract. Each VM tracks its own replication state on zapdb under Quasar.</p>
<h3>5. Cloud-in-a-Box — one binary, three modes (HIP-0117)</h3>
<p>| Mode | Command | Topology | |------|---------|----------| | 1 | <code>cloud serve</code> | Single process, NO Kubernetes. All subsystems in-process, per-tenant SQLite, datastore as subprocess or gracefully absent. Laptop/edge/single-node. | | 2 | <code>cloud cluster init</code> | Binary FETCHES k3s (does not embed it), bootstraps the cluster, installs the operator, hands reconciliation to <code>services.hanzo.ai</code> CRs. Bare metal → HA in one command. (staged) | | 3 | <code>helm install</code> | BYO Kubernetes: <code>cloud/helm/cloud</code> deploys the same image into an existing cluster. |</p>
<h3>6. The edges: gateway, console, visor</h3>
<ul><li><strong>gateway</strong> (HIP-0004, <code>api.hanzo.ai</code>) — the unified AI provider interface:</li></ul>
<p> one OpenAI-compatible surface over 100+ providers, BYO AI/keys.</p>
<ul><li><strong>console</strong> (<code>console.hanzo.ai</code>) — the unified dashboard: per-product</li></ul>
<p> metered usage and 402 balance-gating. The console SPA is <code>go:embed</code>&#x27;d into the cloud binary (real <code>hanzoai/console</code> static build; the Dockerfile fails hard if the SPA is missing — no placeholder builds).</p>
<ul><li><strong>visor</strong> — fleet autoscaler across any nodes and any cloud provider</li></ul>
<p> (BYO provider). 8 Kubernetes clusters operated today.</p>
<h3>7. CI/CD</h3>
<ul><li><strong>Gitea Actions on git.hanzo.ai is the native CI</strong> — GH-Actions-compatible,</li></ul>
<p> runs the same <code>.github/workflows</code> on Hanzo runners. GitHub is the OSS mirror. No GitHub-hosted builders, ever.</p>
<ul><li>Images: <code>ghcr.io/hanzoai/<em></code> for Hanzo, <code>ghcr.io/luxfi/</em></code> for Lux — never mix.</li><li>The operator reconciles <code>services.hanzo.ai</code> CRs; devs ship via CI/CD, not</li></ul>
<p> kubectl.</p>
<h2>Quick Reference</h2>
<p>| Item | Value | |------|-------| | Repo | <code>github.com/hanzoai/cloud</code> (<code>~/work/hanzo/cloud</code>) | | Core | 977-LOC shim on zip + <code>cloud.Register</code> registry | | Plugins | <code>clients/*</code> — 74,561 LOC, 76:1 plugin:core | | Server framework | <code>github.com/hanzoai/zip</code> (<code>~/work/zap/zip</code>) | | Transport | ZAP only (HIP-0114); ZAP port 9653 | | pb boundary | <code>zap2pb</code>/<code>pb2zap</code>/<code>zapc</code> at the OTel edge only | | Storage | SQLite per-tenant; datastore (ClickHouse) for telemetry | | Consensus | Lux Quasar + zapdb — no ZooKeeper/raft/etcd | | Entrypoints | <code>cmd/cloud</code> (full surface), <code>cmd/hanzo</code> (subcommand dispatcher) | | Helm chart | <code>cloud/helm/cloud</code> | | One-binary size | 303.6 MiB with embedded console SPA | | AI surface | gateway HIP-0004 at api.hanzo.ai | | Metering | console.hanzo.ai, 402 balance-gating |</p>
<h3>Key Guidelines</h3>
<pre><code>✅ DO: add functionality as a clients/* plugin registered via cloud.Register
✅ DO: hold ZAP types end-to-end; convert to pb only at the OTel edge
✅ DO: default to SQLite per-tenant; fail closed when config is missing
✅ DO: build each service standalone AND as a subsystem (HIP-0116)
❌ DON&#x27;T: introduce gRPC, protobuf, or a second RPC stack
❌ DON&#x27;T: add a new standalone pod for something the binary already embeds
❌ DON&#x27;T: reach for ZooKeeper/etcd/raft — Quasar + zapdb is the substrate
❌ DON&#x27;T: build images locally — Gitea Actions CI on our runners only</code></pre>
<h2>Anti-Patterns</h2>
<p>❌ <strong>&quot;Let&#x27;s split this subsystem into its own microservice&quot;</strong> — the split already exists: it&#x27;s the same code as a plugin VM over ZAP (HIP-0116). Process topology is deployment configuration, not architecture.</p>
<p>❌ <strong>&quot;Add a proto file for this internal API&quot;</strong> — Hanzo code holds ZAP types only. If you are writing <code>.proto</code>, you are at the OTel edge or you are wrong.</p>
<p>❌ <strong>&quot;docker compose up postgres for local dev&quot;</strong> — <code>cloud serve</code> runs the whole cloud from one binary with SQLite. That IS local dev.</p>
<h2>Related Skills</h2>
<ul><li><code>skills/hanzo/hanzo-cloud.md</code> — the cloud binary operationally (config, URLs, deploy)</li><li><code>skills/hanzo/hanzo-zap.md</code> — ZAP protocol details and the MCP mapping</li><li><code>skills/hanzo/hanzo-gateway.md</code> — the HIP-0004 AI gateway at api.hanzo.ai</li><li><code>skills/hanzo/hanzo-o11y.md</code> — observability, embedded o11y subsystem</li><li>luxfi/skills <code>lux-zap-substrate</code> — the Lux substrate (Quasar + zapdb + zip + lpm) Hanzo builds on</li></ul>
<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-architecture.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>