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: console.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-...

Your first call

The catalogue of models the gateway currently serves. It is a read, it needs nothing but the key, and it is the same operation on all four surfaces.

hanzo models list

npm i hanzo

import { Hanzo } from 'hanzo'

const hanzo = new Hanzo({ apiKey: process.env.HANZO_API_KEY })
const models = await hanzo.models.list()

pip install hanzo

from hanzo import Hanzo

hanzo = Hanzo(api_key=os.environ["HANZO_API_KEY"])
models = hanzo.models.list()

go get github.com/hanzoai/go-sdk

client := hanzo.NewClient(hanzo.WithAPIKey(os.Getenv("HANZO_API_KEY")))
models, err := client.Models.List(ctx)

cargo add hanzo

let hanzo = hanzo::Client::from_env()?;
let models = hanzo.models().list().await?;

// Package.swift: .package(url: "https://github.com/hanzoai/swift-sdk", from: "1.0.0")
let hanzo = Hanzo(apiKey: ProcessInfo.processInfo.environment["HANZO_API_KEY"]!)
let models = try await hanzo.models.list()

// build.gradle.kts: implementation("ai.hanzo:sdk:latest.release")
val hanzo = Hanzo(apiKey = System.getenv("HANZO_API_KEY"))
val models = hanzo.models.list()

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 — Python, TypeScript, Go, Rust, C++, Swift and Kotlin, generated from the same description the CLI and the tools are.
• MCP — one door 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.

Something that costs money

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

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.

Run the whole cloud yourself

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

hanzo up cloud

Bare hanzo up is the same thing — cloud is the default. Name one service to run it alone: hanzo up iam, hanzo up kms, hanzo up gateway, hanzo up storage, hanzo up pubsub. See Run your own for what that means and what it needs.