Hanzo
Sign InGet API Key
Platform

Hanzo Chat

The chat platform on Hanzo Cloud — enso and Zen models, MCP tools, agents, and conversation history.

Hanzo Chat

Hanzo Chat is the chat platform on Hanzo Cloud. It runs our own models — the enso frontier family and the Zen open-weight family — with MCP tools, agents, file uploads, vision and conversation history. Models from outside labs are carried too, and appear in the same model menu.

Features

  • enso: The frontier family — enso-flash, enso, enso-ultra
  • Zen: Chat, reasoning, code, vision, safety, embeddings and the other modalities
  • MCP Tools: Model Context Protocol integration for extending model capabilities
  • Agents: Configurable AI agents with custom system prompts and tool access
  • Vision & Multimodal: Image analysis via zen-vl
  • File Uploads: Upload documents, images, and code for analysis
  • Streaming: Real-time streaming responses for all models
  • Conversation History: Persistent chat history backed by MongoDB
  • Multi-Tenant: Organization-isolated workspaces via Hanzo IAM

Architecture

+---------------------------------------------------------------+
|                         HANZO CHAT                             |
+---------------------------------------------------------------+
|                                                                |
|  +------------------+  +------------------+  +---------------+ |
|  |   React Client   |  |   Node.js API    |  |   MongoDB     | |
|  |                  |  |                  |  |               | |
|  |  - Chat UI      |  |  - REST API      |  |  - Messages   | |
|  |  - Model Select |  |  - WebSocket     |  |  - Convos     | |
|  |  - File Upload  |  |  - MCP Broker    |  |  - Users      | |
|  |  - Agent Config |  |  - Auth          |  |  - Presets    | |
|  +------------------+  +------------------+  +---------------+ |
|                                                                |
|  +----------------------------------------------------------+ |
|  |                  Provider Layer                            | |
|  |  Zen . OpenAI . Anthropic . Google . Meta . ...        | |
|  +----------------------------------------------------------+ |
|                                                                |
+---------------------------------------------------------------+

Endpoints

EnvironmentURL
Productionhttps://chat.hanzo.ai
APIhttps://api.hanzo.ai/v1
Localhttp://localhost:3081

Quick Start

Cloud

  1. Go to chat.hanzo.ai
  2. Sign in with your Hanzo account
  3. Your $5 free credit is applied automatically
  4. Select a model and start chatting

Self-Hosted

# Clone the chat template
git clone https://github.com/hanzoai/chat-template
cd chat-template

# Configure
cp .env.example .env
# Edit .env with your API keys

# Start
make up

# Open http://localhost:3081

Docker

# compose.yml
services:
  chat:
    image: ghcr.io/hanzoai/chat:latest
    ports:
      - "3081:3081"
    volumes:
      - ./chat.yaml:/app/chat.yaml:ro
    environment:
      - HANZO_API_KEY=${HANZO_API_KEY}
      - MONGO_URI=mongodb://mongo:27017/chat
    depends_on:
      - mongo

  mongo:
    image: mongo:7
    volumes:
      - mongo_data:/data/db

volumes:
  mongo_data:

Configuration

Chat is configured via chat.yaml (mounted into the container):

# chat.yaml
version: 1.0.0
cache: true

endpoints:
  hanzo:
    # The enso and Zen families, on api.hanzo.ai
    baseURL: "https://api.hanzo.ai/v1"
    apiKey: "${HANZO_API_KEY}"
    models:
      default:
        - enso
        - enso-flash
        - enso-ultra
        - zen5
        - zen5-pro
        - zen5-coder
        - zen5-flash
        - zen-vl
        - zen-guard
      fetch: true  # Auto-discover the rest of the catalogue, carried models included

  # Direct provider endpoints (optional)
  openAI:
    apiKey: "${OPENAI_API_KEY}"
    models:
      default:
        - gpt-4o
        - o3
        - o4-mini

  anthropic:
    apiKey: "${ANTHROPIC_API_KEY}"
    models:
      default:
        - claude-opus-4-20250514

Models

Our models

Available by default. Rates are USD per 1M tokens.

ModelForInputOutput
enso-ultraFrontier work that has to be right$5.00$25.00
ensoThe frontier default$4.00$20.00
enso-flashFrontier quality where latency matters$2.00$4.00
zen5General chat and reasoning$4.18$13.20
zen5-proLonger, harder reasoning$4.18$8.35
zen5-coderCode generation and review$4.18$13.20
zen5-flashHigh-volume work where latency matters$0.34$0.67
zen-vlImages in, text out$0.60$1.80
zen-guardSafety classification$1.95$1.95
zen-imageImage generation$0.24--
zen-embeddingEmbeddings$0.06$0.06
zen-rerankReordering retrieval results$0.03$0.03

zen-voice, zen-music, zen-video and zen-foley cover the remaining modalities. GET /v1/models is the source of truth for the live catalogue and current rates.

Carried models

Models from outside labs are carried as well, and you reach one by naming its id on this same endpoint with this same key. That is a convenience for teams who need a specific outside model in one workflow. GET /v1/models lists what is available today.

Pricing

  • $5 free credit on every new account (expires in 30 days)
  • Prepaid billing -- add credits via console.hanzo.ai
  • $1 minimum balance required to make API calls
  • Starting at $0.34/MTok input (zen5-flash)
  • No surprise bills -- service stops when credits are depleted

See Zen Pricing for the full pricing table.

MCP Tools

Chat supports Model Context Protocol tools for extending model capabilities:

# chat.yaml (tools section)
mcpServers:
  filesystem:
    command: npx
    args:
      - "@hanzo/mcp-filesystem"
    env:
      ALLOWED_DIRS: "/data"

  web:
    command: npx
    args:
      - "@hanzo/mcp-web"

Agents

Create custom AI agents with specific system prompts, model selection, and tool access:

# chat.yaml (agents section)
agents:
  - name: "Code Reviewer"
    model: "zen5-coder"
    systemPrompt: |
      You are a senior code reviewer. Analyze code for bugs,
      security issues, and style improvements.
    tools:
      - filesystem
      - web

  - name: "Research Assistant"
    model: "zen5-pro"
    systemPrompt: |
      You are a research assistant. Search the web, analyze
      documents, and provide citations.
    tools:
      - web

Environment Variables

# Required
HANZO_API_KEY=hk-your-api-key

# Database
MONGO_URI=mongodb://localhost:27017/chat

# Optional: Direct provider keys (bypass gateway)
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_AI_API_KEY=...

# Auth (optional)
DOMAIN_SERVER=https://chat.yourdomain.com
DOMAIN_CLIENT=https://chat.yourdomain.com

# Branding (optional)
APP_TITLE=Hanzo Chat
CUSTOM_FOOTER=Powered by Hanzo AI

API Endpoint

The Chat API is available at api.hanzo.ai:

# Chat completion via Hanzo API
curl 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"}]
  }'
  • Zen Models -- Full model catalog with specs and pricing
  • AI API -- The inference API: chat, embeddings, images and reranking
  • Hanzo MCP -- Model Context Protocol tools
  • Gateway Service -- API gateway deployment and configuration
  • Console -- Billing, usage, and API key management

How is this guide?

Last updated on

On this page

Hanzo ChatFeaturesArchitectureEndpointsQuick StartCloudSelf-HostedDockerConfigurationModelsOur modelsCarried modelsPricingMCP ToolsAgentsEnvironment VariablesAPI EndpointRelated