Hanzo Cloud

Hanzo Cloud is the core AI Cloud OS that powers api.hanzo.ai. It provides a unified model gateway (ZAP protocol), knowledge base with RAG, container orchestration, and infrastructure management across the Hanzo ecosystem.

Features

Three Protocols: REST API, MCP (Model Context Protocol), ZAP (Zero-overhead API Protocol)

Model Gateway: Route inference requests across 50+ models and providers

Knowledge Base: RAG-powered document stores with vector embeddings

Container Cloud: Kubernetes application templates and management

Multi-Provider: OpenAI, Anthropic, Fireworks, DO-AI, and custom Zen models

IAM Authentication: OAuth2/OIDC via Hanzo IAM, API keys (hk-*), widget keys (hz-*)

Usage Billing: Per-request metering via Hanzo Commerce API

Rate Limiting: Dynamic tier-based limits (free → enterprise)

Node Management: Remote infrastructure via VNC/RDP

Architecture

┌──────────────────────────────────────────────────────────────────┐
│                        HANZO CLOUD                               │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌─────────────────────┐    ┌──────────────────────────────┐    │
│  │   ZAP Model Gateway │    │     Knowledge / RAG          │    │
│  │  ┌───────┐ ┌──────┐ │    │  ┌────────┐  ┌───────────┐  │    │
│  │  │OpenAI │ │Zen   │ │    │  │ Stores │  │ Vectors   │  │    │
│  │  │Anthro │ │Models│ │    │  │ (docs) │  │ (embeds)  │  │    │
│  │  │Firew. │ │      │ │    │  └────────┘  └───────────┘  │    │
│  │  └───────┘ └──────┘ │    └──────────────────────────────┘    │
│  └─────────────────────┘                                        │
│                                                                  │
│  ┌─────────────────────┐    ┌──────────────────────────────┐    │
│  │   Auth & Billing    │    │     Container Cloud          │    │
│  │  ┌───────┐ ┌──────┐ │    │  ┌────────┐  ┌───────────┐  │    │
│  │  │ IAM   │ │Comm. │ │    │  │  K8s   │  │ Templates │  │    │
│  │  │ OIDC  │ │ API  │ │    │  │ Apps   │  │           │  │    │
│  │  └───────┘ └──────┘ │    │  └────────┘  └───────────┘  │    │
│  └─────────────────────┘    └──────────────────────────────┘    │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘

Endpoints

Environment	URL	Purpose
Production	`https://api.hanzo.ai`	API gateway
Console	`https://console.hanzo.ai`	Admin UI
Lux Cloud	`https://cloud.lux.network`	Lux network instance

Quick Start

Get an API Key

Create an API key at console.hanzo.ai or via the API:

curl -X POST https://api.hanzo.ai/api/add-token \
  -H "Authorization: Bearer $IAM_TOKEN" \
  -d '{"name": "my-key", "organization": "hanzo"}'

Chat Completion (OpenAI-Compatible)

curl https://api.hanzo.ai/v1/chat/completions \
  -H "Authorization: Bearer hk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "zen4-mini",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

SDK Usage

import OpenAI from 'openai'

const client = new OpenAI({
  baseURL: 'https://api.hanzo.ai/v1',
  apiKey: 'hk-your-api-key'
})

const response = await client.chat.completions.create({
  model: 'zen4-mini',
  messages: [{ role: 'user', content: 'Hello' }]
})

Protocols

Hanzo Cloud exposes three protocols for accessing AI services:

Protocol	Transport	Use Case
REST	HTTPS (JSON)	Standard OpenAI-compatible API for chat completions, embeddings, models
MCP	stdio / SSE	Model Context Protocol — 260+ tools for AI agents (filesystem, search, browser, etc.)
ZAP	WebSocket (binary)	Zero-overhead API Protocol — native binary streaming for low-latency inference

REST (OpenAI-Compatible)

curl https://api.hanzo.ai/v1/chat/completions \
  -H "Authorization: Bearer hk-your-key" \
  -d '{"model": "zen4-mini", "messages": [{"role": "user", "content": "Hello"}]}'

MCP (Model Context Protocol)

npx @hanzo/mcp --api-key hk-your-key

Or configure in your AI client's MCP settings:

{
  "mcpServers": {
    "hanzo": {
      "command": "npx",
      "args": ["@hanzo/mcp", "--api-key", "hk-your-key"]
    }
  }
}

ZAP (WebSocket)

const ws = new WebSocket('wss://api.hanzo.ai/zap')
ws.send(JSON.stringify({
  type: 'chat.completions',
  model: 'zen4-mini',
  messages: [{ role: 'user', content: 'Hello' }]
}))

Authentication

Hanzo Cloud supports multiple auth methods:

Method	Format	Use Case
IAM API Key	`hk-*`	Server-side API access
IAM JWT	Bearer token	User sessions via hanzo.id
Provider Key	`sk-*`	Direct provider passthrough
Widget Key	`hz-*`	Public-facing chat widgets

All auth flows integrate with Hanzo IAM for identity management.

Rate Limits

Tier	Requests/min	Set By
Free	10	Default
Starter	60	Commerce billing
Pro	300	Commerce billing
Enterprise	1000	Commerce billing

KMS Integration

All secrets (provider API keys, database credentials, IAM client secrets) are managed by Hanzo KMS. See KMS Service Integration for the pattern.

Next Steps

Core concepts: providers, stores, vectors, chats

Configure model, storage, and embedding providers

OpenAI-compatible API and SDK integration

Kubernetes application management

Hanzo Cloud

On this page