hanzo-cloud

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.

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

Hard requirements

  1. ZAP only (HIP-0114): zero gRPC, zero protobuf in Hanzo code. The pb

boundary is zap2pb/pb2zap/zapc at the OTel edge exclusively.

  1. zip is the one server framework — no Beego, no Gin, no echo, no

second framework.

  1. SQLite-primary per-tenant storage; PostgreSQL only for production

multi-instance. Never default to PostgreSQL for local dev.

  1. 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).

  1. IAM identity from hanzo.id; org from the JWT owner claim; 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

Category: Hanzo Ecosystem Related: cloud, one-binary, zip, zap, plugins, subsystems, white-label, console Prerequisites: Go, the hanzo-cloud-architecture skill