7.0 KiB
Hanzo Cloud - The Unified One-Binary Cloud
Category: Hanzo Ecosystem
Canonical spec: HIP-0106 (one binary), HIP-0114 (ZAP), HIP-0116 (plugin VMs), HIP-0117 (deploy modes)
Related Skills: hanzo-cloud-architecture/SKILL.md (read first), hanzo/hanzo-zap.md, hanzo/hanzo-gateway.md, hanzo/hanzo-console.md, hanzo/hanzo-iam.md
Overview
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. It is built
on zip (github.com/hanzoai/zip, the ZAP-native high-performance server):
a 977-LOC shim plus cloud.Register(name, order, mount) and 74,561 LOC
of plugins under clients/* (76:1 plugin:core). The console SPA is
go:embed'd (real hanzoai/console static build; 303.6 MiB one-binary;
fail-hard Dockerfile). The same artifact powers api.hanzo.ai,
api.lux.cloud, api.zoo.cloud, and every white-label surface — brand,
enabled subsystems, and tenant scope are deployment configuration.
Naming note: the former "AI provider management platform" content that
used to live at hanzoai/cloud was renamed to hanzoai/ai and mounts as the
ai subsystem inside this binary. White-label fork target is hanzoai/cloud.
When to use
- Working on any embedded subsystem (
clients/*) or the cloud core - Standing up a full Hanzo cloud locally (
cloud serve— no Kubernetes) - Deploying or white-labeling a cloud surface
- Managing AI providers/keys (the
aisubsystem + gateway HIP-0004) - Wiring per-product metered usage and 402 balance-gating via console
Hard requirements
- ZAP only (HIP-0114): zero gRPC, zero protobuf in Hanzo code. The pb
boundary is
zap2pb/pb2zap/zapcat the OTel edge exclusively. - zip is the one server framework — no Beego, no Gin, no echo, no second framework.
- SQLite-primary per-tenant storage; PostgreSQL only for production multi-instance. Never default to PostgreSQL for local dev.
- Subsystems fail closed: an embed without its required config refuses
to mount. Disabled-by-default in production; deployments enable
explicitly via
cfg.Enable(flags/env). - IAM identity from hanzo.id; org from the JWT
ownerclaim; all data scoped to org.
Quick reference
| Item | Value |
|---|---|
| Repo | github.com/hanzoai/cloud (~/work/hanzo/cloud) |
| Entrypoints | cmd/cloud (full surface), cmd/hanzo (subcommand dispatcher) |
| Registry | cloud.Register / cloud.RegisterWithShutdown (build.go) |
| Subsystem set | subsystems bundle (one source of truth, blank-imported) |
| Plugins | clients/* (admin, ai, billing, console, iamsvc, kmssvc, kafka, notify, o11y, tasksvc, ...) |
| Server | github.com/hanzoai/zip — ZAP primary + HTTP extra, one Listen |
| Console | go:embed SPA (webui.go, clients/console) |
| Helm chart | cloud/helm/cloud |
| Image | ghcr.io/hanzoai/cloud (Gitea Actions CI, GH mirror) |
| API surface | api.hanzo.ai (/v1/..., never /api/ prefixes) |
| Dashboard | console.hanzo.ai (usage metering, 402 balance-gating) |
Architecture
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)
Each hanzoai/<repo> service still builds standalone; inside cloud it is a
subsystem, and (HIP-0116, staged) the same code runs as an out-of-process
plugin VM dialed over ZAP and distributed via luxfi/lpm. In-process vs
out-of-process is deployment topology, not architecture.
Adding a subsystem
// clients/example/example.go
package example
import "github.com/hanzoai/cloud"
func init() {
cloud.Register("example", 50, mount) // name, mount order, mount func
}
func mount(app cloud.App, cfg cloud.Config) error {
if cfg.ExampleDSN == "" {
return cloud.ErrNotConfigured // fail closed, never degrade silently
}
app.Get("/v1/example/:id", handler) // /v1/, never /api/
return nil
}
Then add it to the subsystems bundle — the ONE place the set is defined.
Running
# 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
API key usage (the ai subsystem + gateway)
export HANZO_API_KEY=sk-...
curl https://api.hanzo.ai/v1/chat/completions \
-H "Authorization: Bearer ${HANZO_API_KEY}" \
-H "Content-Type: application/json" \
-d '{"model": "zen-70b", "messages": [{"role": "user", "content": "Hello"}]}'
The gateway (HIP-0004) is the unified AI provider interface — 100+ providers, BYO keys. Usage is metered per product in console; exhausted balance returns 402 at the gate.
Troubleshooting
| Issue | Cause | Solution |
|---|---|---|
| Subsystem missing from a deploy | Not in cfg.Enable |
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 | cloud serve 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 (zap2pb) |
Related Skills
hanzo-cloud-architecture/SKILL.md— the canonical architecture skillhanzo/hanzo-zap.md— ZAP transport and MCP mappinghanzo/hanzo-gateway.md— HIP-0004 AI gateway at api.hanzo.aihanzo/hanzo-console.md— dashboard, metering, LLM observabilityhanzo/hanzo-iam.md— identity (embeddediamsvc)
Category: Hanzo Ecosystem Related: cloud, one-binary, zip, zap, plugins, subsystems, white-label, console Prerequisites: Go, the hanzo-cloud-architecture skill