Sovereign, self-hostable AI infrastructure, developer platform, and agentic operating system.
One unified contract. Zero vendor lock-in. Self-contained across your laptop, edge nodes, or private GPU clusters.

hanzo.ai · Documentation · LLM Context (llms.txt) · HIPs Specifications · Skills · Market · Forge · CLI (hanzo.sh)

Hanzo unifies every layer of the modern cloud and AI stack into an open, zero-trust lifecycle:

[Clients, SDKs, Coding Agents, Browsers]
                   │
                   ▼
  Cloudflare (Edge WAF, DDoS, Anycast SSL)
                   │
                   ▼
  AWS Network Load Balancer (NLB)
                   │
                   ▼
  hanzoai/ingress (L4/L7 Ingress Controller, TLS Termination & Subdomain Routing)
                   │
                   ▼
  hanzoai/gateway (Stateless Gateway: JWT Auth, Quota/Rate Limiting, Identity Injection)
                   │
                   ▼
  hanzoai/cloud (Unified "One Binary" Control Plane — Lazy-Loads All /v1/* APIs)
   ├─ IAM (hanzo.id) & KMS (kms.hanzo.ai)
   ├─ Model Hub (500+ LLMs, Routing, Prompting, RAG)
   ├─ Multi-Tenant BaaS (Base + Encrypted SQLite)
   ├─ Headless Commerce & Billing (Crypto / Card / Wire Clearinghouse)
   ├─ Workflow Automation (Auto + Tasks over ZAP)
   ├─ Native Sandbox Orchestrator (Visor + VM over ZAP)
   ├─ Realtime ZAP Telemetry Ingestion (o11y Spans/Metrics/Logs)
   └─ In-Cluster BuildKit Job Dispatch (/v1/build)
                   │
    ┌──────────────┴────────────────────────────┐
    ▼                                           ▼
Sovereign Data Plane                     hanzoai/ai, Tasks & Agents
• Base (Multi-tenant BaaS)                      │
• SQLite (Hardware Encrypted)                   ▼ (Credential-Free Outbound Call)
• SQL (Relational Engine)                hanzoai/egress (Outbound Security Boundary)
• Datastore (Columnar OLAP Engine)              │ (Rate Limits, Redaction, Audit Spans)
• KV (In-Memory RESP/ZAP)                       ▼
• S3 (S-Chain Object Store)              Hanzo KMS & MPC Nodes
                                         (In-Flight Ephemeral Key Unwrapping / HSM)
                                                │
                                                ▼ (Egress Dispatch With Injected Auth)
                                         External Partner APIs & BYOK Providers
                                         (Model Providers, Payment Gateways, Webhooks)

hanzoai/ingress ➔ hanzoai/gateway ➔ hanzoai/cloud ➔ hanzoai/ai ➔ hanzoai/egress ➔ hanzoai/kms & hanzoai/mpc

Governed by HIP-0143: Egress Outbound Trust Boundary, Hanzo enforces a zero-leakage perimeter for all external network interactions:

1. Credential-Free Internal Calls: Internal services (hanzoai/ai, hanzoai/auto, hanzoai/tasks, coding agents) never store or receive raw external API keys. Outbound requests reference only scoped credential identifiers (credential_id).
2. Outbound Boundary Enforcement (hanzoai/egress): Network policies force all outbound traffic through the egress proxy. egress evaluates organization rate limits, checks token balance tariffs, scrubs internal headers, and records tamper-evident audit spans.
3. In-Flight Key Injection via Split-MPC: hanzoai/egress contacts Hanzo KMS (hanzoai/kms, hanzoai/mpc). Quorum threshold shares (FROST/CGGMP21/Pulsar) or physical hardware HSMs unwrap the key in-flight, injecting the token directly into the outbound HTTP authorization header in RAM.
4. External Dispatch: Requests are dispatched over TLS to external providers. Credentials never touch disk, container environment variables, or model reasoning contexts, and responses stream directly back through egress.

To ensure client libraries, documentation, CLI tools, and agent definitions never drift from production code, Hanzo enforces a single-source-of-truth generation pipeline:

Go Live Router (zap-proto/zip & hanzoai/cloud)
                   │
                   ▼
  make openapi ➔ GET /v1/openapi.json
  (Canonical 1,800+ path golden contract; verified by CI)
                   │
                   ▼
  hanzoai/openapi Generator (generate.py, sdks.yaml)
                   │
  ┌────────────────┼────────────────┬────────────────┐
  ▼                ▼                ▼                ▼
Rust CLI        MCP Server      Client SDKs       Documentation
(hanzoai/cli)   (hanzoai/mcp)   (14+ Languages)   (docs.hanzo.ai, llms.txt)

zap-proto/zip & hanzoai/cloud ➔ hanzoai/openapi ➔ hanzoai/cli · hanzoai/mcp · docs.hanzo.ai

1. Declared Once in Code: Handlers, routes, request/response types, and security schemes are written once in Go using zap-proto/zip.
2. Golden Contract Verification: Running make openapi compiles the live route table into openapi.yaml and private.yaml. If an engineer edits a route or model without updating the golden spec, CI fails.
3. Automated SDK & Tool Projection: hanzoai/openapi automatically regenerates the Rust CLI, Model Context Protocol tools, and client SDKs across 14+ programming languages, stamping each release with a cryptographic .spec-lock.

• Single Binary Footprint: Run on a laptop with zero cloud dependencies.
• One-Command Boot (hanzo up): Boots the entire unified Hanzo cloud locally, lazy-loading each service (/v1/*) on-demand!
• CLI Entry: hanzo CLI installed via curl -fsSL https://hanzo.sh | sh. Login as a user or administrator with hanzo auth login.
• Local Cloud Server: hanzoai/cloud runs unencrypted for development via CLOUD_DEV_UNENCRYPTED=1 make build.
• Local BaaS: hanzoai/base boots in-process on port 8090 using SQLite with immediate REST and realtime SSE change streams.
• Local Inference: hanzoai/engine serves quantized GGUF models on CPU, Apple Silicon Metal, or CUDA over /v1/chat/completions.
• Coding Agents: hanzo dev runs coding sessions locally within hanzoai/kata microVM sandboxes over standard I/O MCP.

• High-Availability Kubernetes: Deployed across sovereign clusters (hanzo-k8s, AWS EKS, etc).
• Ingress & Identity Injection: Requests pass through AWS Network Load Balancers (NLB), hanzoai/ingress (handling TLS termination and certificates), and stateless hanzoai/gateway (validating RSA-signed JWTs from iam and injecting trusted X-User-Id / X-Org-Id headers downstream).
• Unified Control Plane: hanzoai/cloud mounts all core subsystems dynamically using the zip framework without code divergence.
• Sovereign GPU Inference: Model routing passes through hanzoai/ai and hanzoai/kai, executing against resident hanzoai/engine inference engine and hanzoai/ml framework.
• Continuous Delivery: Reconciled continuously by Hanzo CD (cd.hanzo.ai, hanzoai/cd) against declarative specs in hanzoai/deploy.

• Database-Agnostic ORM (hanzoai/orm): Governed by HIP-0144: Where State Lives. The Hanzo data layer is completely agnostic of the underlying SQL storage engine:
  • Fast Embedded Local Dev: Defaults to SQLite (with SQLCipher 4 hardware encryption or in-memory) for instant, zero-dependency hanzo up boots without running external database containers.
  • Pluggable Multi-Backend Drivers: Seamlessly switches to external SQL engines — PostgreSQL wire protocol via hanzoai/sql, columnar OLAP via hanzoai/datastore, MySQL, MariaDB, TiDB, and CockroachDB — with identical Go application code.
  • Unified Type-Safe API: Provides generic Model[T], schema auto-migrations, transactional safety, and zero-allocation query building.
• State Ranks (HIP-0144):
  • Rank 1 (Per-Tenant File): hanzoai/base provisions isolated, per-org SQLite databases (/orgs/<org>/data.db) encrypted with organization-specific SQLCipher 4 keys derived from Hanzo KMS.
  • Rank 2 (Column Store): hanzoai/datastore ingests high-throughput telemetry, analytics, and event streams decoupled over S-Chain object storage (hanzoai/s3).
  • Rank 3 (Shared SQL & KV): hanzoai/sql and hanzoai/kv provide shared clustered relational state and in-memory caches where multi-tenant concurrency requires a centralized server.
• Streaming Replication: Replicated in real time via hanzoai/vfs blocks to S-Chain distributed object storage (hanzoai/s3).
• In-Process JavaScript Hooks: Business logic runs in sandboxed ECMAScript VMs via Goja (.base.js).

• Zero-Copy Protocol (ZAP): Binary communication over port 9653 and /zap WebSockets; 17x faster than standard JSON-RPC.
• Reactive Database Streams: Collection changes in Base immediately broadcast over Server-Sent Events (SSE).
• Telemetry Streaming: Node-local OpenTelemetry collectors stream spans, logs, and metrics directly to apps/o11y and Datastore.
• Interactive Agent Sessions: hanzo dev sessions stream live terminal PTY output, diff trees, and model reasoning to Mission Control.

• Native Userspace Sandbox (hanzoai/visor): Lightweight application kernel and container sandbox written in Go, communicating natively over the zero-copy ZAP binary protocol instead of gRPC.
• Low Latency & High Density: Delivers sub-millisecond cold starts and significantly lower memory footprints than hypervisors (such as Firecracker), providing the high-density isolation necessary for agent fleets.
• PaaS & Execution Primitives: Directly powers ephemeral runner dispatch (POST /v1/runner), interactive coding sessions (hanzo dev), and code evaluation sandboxes.

• Concrete Syntax Trees (AST): Parsed in-process via hanzoai/ast (grammar parser generator across 40+ programming languages) into queryable s-expression CST nodes.
• Language Server Protocol (LSP): hanzoai/lsp resolves cross-file definitions, type hierarchies, hover docs, and diagnostics without external IDE processes.
• Trigram Inverted Index (tgram): hanzoai/tgrep builds 3-character sub-token posting lists across git repositories, providing sub-millisecond regex code search.
• Semantic Vector & Graph Backend: Code chunks are embedded and indexed via hanzoai/vector (HNSW) and linked to ontology nodes via hanzoai/graph (distributed graph engine over luxfi/zapdb), enabling hybrid semantic discovery at POST /v1/semantic.

• In-Cluster Multi-Arch BuildKit: Invoked via POST /v1/build in hanzoai/cloud, dispatching isolated container builds with zero host Docker daemon exposure.
• Ephemeral MicroVM Runners: POST /v1/runner allocates just-in-time microVMs (hanzoai/git-runner) for isolated code evaluation and test suites.
• Artifact & Package Distribution: Multi-arch container images and Helm charts push to oci.hanzo.ai (backed by hanzoai/s3), while language dependencies resolve via pkg.hanzo.ai.
• Forge & Hanzo CD Reconciler: Hanzo Forge (forge.hanzo.ai / hanzoai/git) hosts repositories, PRs, and Kanban project boards, while Hanzo CD (cd.hanzo.ai / hanzoai/deploy) continuously syncs declared Helm charts into production.

• Native Exception Tracking (hanzoai/sentinel): Ingests standard error envelope protocols (/api/{project_id}/envelope/, /api/{project_id}/store/) from client SDKs with zero code modifications, providing crash capture and stack-frame unwinding (ghcr.io/hanzoai/sentry).
• High-Throughput Event Ingestion (POST /v1/event): High-throughput clickstream and telemetry ingestion via lightweight, cookieless tag.js auto-capture.
• Web & Product Analytics (analytics.hanzo.ai): Real-time traffic, page views, bounce rates, and referrer metrics respecting strict sovereign privacy and zero third-party cookie leakage.
• Business Intelligence & OLAP Warehouse (insights.hanzo.ai & hanzoai/datastore): Columnar OLAP engine decoupled over S-Chain object store (hanzoai/s3). Powers arbitrary SQL aggregations, retention cohorts, conversion funnels, and revenue attribution.
• Event Streaming & Protocol Adapters: In-memory and persisted event pub/sub via hanzoai/pubsub over ZAP binary transport (port 9653), with zero-code protocol bridges for Kafka (hanzoai/kafka) and AMQP message queues (hanzoai/amqp).

• Sovereign Commerce Engine (hanzoai/commerce): Governed by HIP-1220. Built on Hanzo's foundational commerce, analytics, and billing platform.
• Headless Agent Provisioning: Fully optimized for autonomous AI agents. Any agent can programmatically provision an organization, generate an API key, test on the free tier, and autonomously top up compute credits via native cryptocurrency (EIP-712 USDC / native MPC treasury rails), saved payment cards, or bank wires.
• Customer Billing & Metering (hanzoai/billing): Real-time spend tracking, balance ledgers, usage metering (/v1/usage, HIP-1313), and customer billing portal (billing.hanzo.ai).
• Financial AI & Treasury Rails (hanzoai/treasury, hanzoai/ledger): Governed by HIP-1001 and HIP-1221. Multi-tenant double-entry accounting ledger (ledger), bank clearinghouse connections, automated payment routing, and financial reconciliation.
• Multi-Chain Key Custody & Wallet (hanzoai/wallet): Governed by HIP-1161. Multi-chain SIWx signature verification, automated agent clearinghouse, and secure key custody.

• Sovereign Equity & Cap Table Management (hanzoai/captable): Governed by HIP-1111. Sovereign equity, share classes, option pools, stakeholder ledgers, and automated vesting schedules (captable.hanzo.ai).
• Cryptographic Tamper-Evident E-Signatures (hanzoai/esign): Governed by HIP-1125. Self-hosted document e-signature platform with verifiable digital audit trails, hash proofs, and field placement (esign.hanzo.ai).
• Secure Virtual Data Rooms (hanzoai/dataroom): Governed by HIP-1121. Encrypted document sharing with dynamic viewer watermarking, role-based granular access revocation, and tamper-evident audit logs (dataroom.hanzo.ai).

• Core ML Framework (hanzoai/ml): Multi-backend Rust tensor computation and machine learning toolkit (hanzo-ml, CUDA, Metal, ROCm, Vulkan).
• LLM Inference Server (hanzoai/engine): High-performance multimodal inference server supporting GGUF, CUDA, Metal, and ISQ quantization over /v1/chat/completions.
• Sovereign Node & P2P AI Mesh (hanzoai/node): Blockchain node embedding the inference engine, shipped with the Hanzo desktop app to mine AI and connect local compute with cloud inference — paving the way for a global decentralized AI network for distributed training, inference, and a P2P compute marketplace.

• Sovereign Identity Protocol (did:hanzo:<org>:<user>): Governed by HIP-0097 and @hanzo/iam (hanzo.id). Cryptographic user authentication, organization membership, and RBAC via RSA/ECDSA-signed JWT claims.
• Per-Tenant Data & Key Isolation: Every organization gets an independent SQLite database at /orgs/<org>/data.db encrypted with organization-specific SQLCipher 4 keys derived from Hanzo KMS, coupled with isolated ZAP pub/sub topic trees.
• Frontend Runtime Customization: Developers customize application look and feel dynamically using mod themes (@hanzo/mod), @hanzo/ui, and @hanzo/design tokens without rebuilding or recompiling frontend distributions.
• Backend In-Process Sandboxes: Users write custom business logic and backend extensions that execute safely in sandboxed environments:
  • ECMAScript/JS Sandboxes: Fast execution via Goja/V8 (.base.js) hooks for record lifecycle events and REST API extensions.
  • WebAssembly Sandboxes: Multi-language extensions compiled to Wasm running inside wasm runtimes and isolated kata microVM sandboxes.
• Enterprise High-Performance wasm2go AOT: In enterprise production, performance-critical Wasm modules are compiled directly into native Go assembly (amd64.s/arm64.s) via hanzoai/wasm2go, running natively inside the "One Binary" with zero CGo overhead and zero interpreter tax.

Governed by HIP-0136: One Secret, One Path and HIP-0409: KMS CRD, Hanzo KMS (kms.hanzo.ai, hanzoai/kms) is a thin, high-performance Go service layered over hanzoai/mpc:

                       Hanzo KMS (kms.hanzo.ai)
                                  │
    ┌─────────────────────────────┼─────────────────────────────┐
    ▼                             ▼                             ▼
1. SPLIT MPC BACKEND        2. OPTIONAL HARDWARE HSM       3. ENVELOPE ENCRYPTION
Threshold Secret Sharing    Physical Security Modules     Local Hardware Accelerated
• FROST (Schnorr threshold) • PKCS#11 / YubiHSM           • AES-256-GCM / Poly1305
• CGGMP21 (ECDSA threshold) • AWS CloudHSM                • SQLCipher 4 At-Rest Engine
• Pulsar (Ring-LWE PQ)      • Google Cloud KMS / Azure    • Memory-only Grant Decryption

• Split MPC Backend: Private master keys never exist on a single machine. Key shares are computed and distributed across independent threshold nodes via FROST (Schnorr), CGGMP21 (ECDSA), and Pulsar (Ring-LWE lattice post-quantum threshold signatures).
• Optional Hardware HSM: Enterprise deployments can bind root keys to dedicated hardware security modules via standard PKCS#11, YubiHSM, AWS CloudHSM, or cloud key vaults.
• Post-Quantum Cryptography Suite: Implements ML-KEM-768 (Kyber key encapsulation), ML-DSA-65 (Dilithium digital signatures), and Pulsar to protect data against store-now-decrypt-later nation-state adversaries.
• Published Keys vs. Secret Keys:
  • Published Keys (Identity & Verification): Ed25519 and Secp256k1 public keys, DID documents (did:hanzo:<org>:<user>, HIP-0097), and public JWKS (https://hanzo.id/.well-known/jwks.json). Downstream clients and gateways verify tokens, signatures, and EIP-712 payment authorizations client-side with zero network roundtrips.
  • Secret Keys (KMS Sealed Envelope): Sensitive credentials (provider API tokens, private keys, database master encryption keys) are sealed in Hanzo KMS under canonical paths /orgs/{org}/users/{user}/connectors/{provider}/{label}. They are never committed to git, written to disk, or injected as plain container environment variables.
• KMS Environments & Zero-Plaintext Grants:
  • KMS_ENV=dev: Allows local developers and offline testing to mock envelope grants in-memory without contacting an external HSM or MPC cluster.
  • KMS_ENV=production: Enforces hardware HSM and split-MPC quorum consensus. Workloads authenticate via Kubernetes ServiceAccount tokens; secret.Boot reads scoped secrets directly into RAM as memory-only grants.

To ensure high performance across every ecosystem without code duplication, Hanzo employs a dual-repository SDK model:

• Top-Level Discovery (hanzoai/<lang>-sdk): The canonical developer entrance, idiomatic wrappers, documentation, and package metadata.
• True Implementation Home (hanzo-<lang>/sdk): The underlying native source code, toolchain-specific build configurations, and compiler pipelines generated directly from api.hanzo.ai/v1/openapi.json via HIP-0139.

The Hanzo ecosystem is organized across specialized, purpose-driven GitHub organizations:

Governed by HIP-0106: The Hanzo Plugin Contract, hanzoai/cloud operates as a unified, light host that dynamically discovers and lazy-loads over 140+ modular production app plugins (apps/*) under /v1/* without code divergence:

• Sovereign Identity, Account & Governance: account (HIP-1200), admission (HIP-1201), compliance (HIP-1115), principal (HIP-1340), trust (HIP-0054), security (HIP-0054), iam (HIP-0111), kms (HIP-0136), mpc (HIP-0413).
• Commerce, Finance & Corporate Rails: billing (HIP-1220), commerce (HIP-1220), marketplace (HIP-1335), ledger (HIP-1001), treasury (HIP-1221), wallet (HIP-1161), captable (HIP-1111), tax (HIP-1338), patent (HIP-1336), usage (HIP-1313), pricing (HIP-1106), allowance (HIP-1101).
• Documents, Contracts & Knowledge: esign (HIP-1125), dataroom (HIP-1121), cms (HIP-1116), helpdesk (HIP-0115), knowledge (HIP-1147), content (HIP-1116).
• AI, Models & Scientific Research: ai (HIP-1211), agents (HIP-1210), zen (HIP-0096), engine (HIP-1124), research (HIP-1334), world (HIP-0506), eval (HIP-1105), benchmark (HIP-1105), prompt (HIP-1211).
• Search, Crawl & Code Intelligence: search (HIP-1147), index (HIP-1132), crawl (HIP-1117), code (HIP-1114), lsp (HIP-1214), graph (HIP-1198).
• Cloud Infrastructure, Telemetry & Networking: compute (HIP-1172), environment (HIP-1339), space (HIP-1337), dns (HIP-1321), flags (HIP-0063), functions (HIP-0060), o11y (HIP-1240), pubsub (HIP-1060), kafka (HIP-1323), amqp (HIP-1326), mq (HIP-1326), sites (HIP-1231), plugin (HIP-0106).

Hanzo operates on a clean separation between Open Source Foundation (hanzoai/*) and Enterprise Sovereign Cloud:

                       The Sovereign Developer Stack
                                     │
      ┌──────────────────────────────┴──────────────────────────────┐
      ▼                                                             ▼
1. PUBLIC OPEN-SOURCE (hanzoai/*)             2. HANZO SOVEREIGN CLOUD 
Fork & Assemble Architecture                   Private Cloud Control Plane
• 100% Sovereign & Self-Hostable               • Proprietary C/C++ AOT via hanzoai/wasm2go
• Single-binary local dev (hanzoai/cloud)     • Bare-metal & GPU manager (apps/visor)
• BaaS data plane (hanzoai/base + SQLite)      • In-cluster BuildKit engine (apps/platform)
• Multi-tenant REST & ZAP streaming            • EIP-712 USDC crypto clearinghouse
• Open MCP tools (AST, LSP, tgrep, vector)     • Kai decision engine & calibration models
• Standard Docker & Helm deployments           • Hardware HSM & Quorum MPC consensus

• Fork and Assemble Locally: Developers can freely fork public repos, assemble their own backend or AI agent mesh on top of Hanzo's canonical /v1/* REST and ZAP binary endpoints, and deploy to their own infrastructure with zero external telemetry or cloud lock-in.
• Enterprise Cloud Enclave: The managed cloud fleet (cloud.hanzo.ai, platform.hanzo.ai) uses wasm2go to compile high-performance native kernels directly into Go assembly (amd64.s/arm64.s), eliminating CGo toolchains while providing high-throughput machine scheduling, JIT runner allocation, and hardware-attested enclave execution.

Clone all 700+ repositories across the Hanzo open-source fleet with a single parallel command:

# Clone the complete Hanzo OSS fleet (700+ repos) into ./hanzo-repos with 16 parallel workers
curl -fsSL https://raw.githubusercontent.com/hanzoai/.github/main/scripts/clone-all.sh | bash -s -- -j 16

Or using the GitHub CLI directly with xargs:

# Stream repo list and clone concurrently
gh repo list hanzoai --limit 1000 --json name --template '{{range .}}{{if not .isArchived}}{{.name}}{{"\n"}}{{end}}{{end}}' | \
  xargs -P 16 -I {} git clone https://github.com/hanzoai/{}.git hanzo-repos/hanzoai/{}

For enterprise members with access to Hanzo Enterprise:

# Clone both public OSS and private enterprise enclaves concurrently via SSH:
curl -fsSL https://raw.githubusercontent.com/hanzoai/.github/main/scripts/clone-all.sh | bash -s -- -o "hanzoai,hanzo-enterprise" -j 16

curl -fsSL https://hanzo.sh | sh
hanzo auth login

# Boots the unified cloud control plane locally, lazy-loading each service on demand
hanzo up

Install our IDE & browser extensions and unified MCP server to control the entire system:

• IDE & Browser Extensions: hanzoai/extension
• Model Context Protocol (Rust & TypeScript): hanzoai/mcp (@hanzo/mcp / hanzo-mcp)
• Python MCP Server:

  uvx hanzo-mcp

hanzo dev
# Or with MCP integration:
gen --mcp

• Admin Backend: admin.hanzo.ai — Operator and cloud observability console
• Cloud Console: platform.hanzo.ai — Unified cloud console for models, compute, data, and billing

Hanzo AI, Inc. — Techstars '17
Open Source under Apache-2.0 and MIT per HIP-0137.