Quickstart

Install

npm i -g hanzo

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

brew install hanzoai/tap/hanzo

git clone https://github.com/hanzoai/cli && cd cli && cargo install --path .

hanzo version

Log in

hanzo auth login

That opens a browser against hanzo.id, Hanzo's identity provider, and stores the resulting credential locally. hanzo auth show prints who you are; hanzo auth list shows every identity on this machine and hanzo auth use switches between them.

For a server, mint a key instead of logging a person in: platform.hanzo.ai → API keys. A secret key resolves to you, so it belongs on a server and never in a browser — Authentication is the whole rule.

export HANZO_API_KEY=sk-...

List the models

The catalogue of models the gateway currently serves. It needs no key at all, and it is the same operation on all four surfaces. An id from it is what a request names as model.

hanzo models list

npm i hanzoai

import { AiApi, Configuration } from 'hanzoai'

const ai = new AiApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }))
const { data } = await ai.getModels()

pip install "hanzoai>=8"   # Python 3.12 or newer

import os
from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import AiApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
models = AiApi(client).get_models()

go get github.com/hanzoai/go-sdk/v8

import hanzoai "github.com/hanzoai/go-sdk/v8"

cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

models, _, err := client.AiAPI.GetModels(context.Background()).Execute()

cargo add hanzo-client

use hanzo_client::apis::{ai_api, configuration::Configuration};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let models = ai_api::get_models(&cfg).await?;

curl https://api.hanzo.ai/v1/models \
  -H "Authorization: Bearer $HANZO_API_KEY"

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Those are one API seen from four places, and the tabs above are the whole difference. Pick the one you will write in:

• CLI — every capability as a command group, one page each.
• SDKs — TypeScript, Python, Go and Rust on a registry today; Java, Kotlin, Swift and C++ behind them. Generated from the same description the CLI and the tools are.
• MCP — one endpoint an agent connects to; the tools are listed one per capability.

HTTP needs no page: it is https://api.hanzo.ai and the key you just exported.

Send a completion

This is the first step that draws down credit; everything above is free to run. zen5 is an id the catalogue lists.

hanzo chat completions --data '{"model":"zen5","messages":[{"role":"user","content":"hello"}]}'

curl -X POST https://api.hanzo.ai/v1/chat/completions \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"zen5","messages":[{"role":"user","content":"hello"}]}'

A 401 names what was missing and where a key comes from; a 402 insufficient_balance means the key is fine and the org has no credit — see Credits & billing. A 429 carries Retry-After, in seconds.

Then read what it drew down:

hanzo billing balance
hanzo usage summary

Credits & billing explains what a credit is and what happens at zero; Pricing is the rate for every model and tool.

Record a fact and read it back

The graph holds what is true of your org's entities, and who said so. Assert one fact, then resolve what holds now.

curl -X POST https://api.hanzo.ai/v1/graph \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"assertions":[{"entity":"acme","relation":"owner","value":"ada","at":"2026-01-01T00:00:00Z","source":"quickstart"}]}'

curl -X POST https://api.hanzo.ai/v1/graph/resolve \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entity":"acme","relation":"owner"}'

The assert answers {"recorded":1,…}; the resolve answers "known":true with the assertion as winner. Graph is the rest of it.

Run the cloud locally

The same binary that serves api.hanzo.ai runs on your machine:

hanzo host serve

cloud is the default, so that is the whole API. Name one service to run it alone: hanzo host serve iam, and likewise kms, gateway, storage, pubsub. hanzo host start runs the same thing in the background, with status and stop beside it.

hanzo up is a different command — it boots k3s in a microVM and hands you a kubeconfig, which is what you want to run your own cluster rather than your own cloud. See Run your own for what each needs.