# Hanzo Chat

URL: https://docs.hanzo.ai/docs/chat

> The chat app on Hanzo Cloud — enso and Zen models, MCP tools, agents, file uploads and RAG. Hosted at chat.hanzo.ai, or self-host it.

Hanzo Chat is the chat app on Hanzo Cloud, built on [LibreChat](https://librechat.ai). It runs our own models — the **enso** frontier family and the **Zen** open-weight family — with MCP tools, configurable agents, file uploads with RAG, vision, conversation history, presets and plugins. Models from outside labs are carried too, and appear in the same model menu.

Available as a hosted service at [chat.hanzo.ai](https://chat.hanzo.ai) or self-hosted via Docker.

## Quick Start

### Hosted (Recommended)

1. Go to [chat.hanzo.ai](https://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

```bash
git clone https://github.com/hanzoai/chat
cd chat
cp .env.example .env
# Edit .env with your HANZO_API_KEY
docker compose up -d
# Open http://localhost:3081
```

### The call

**curl**

```bash
curl https://api.hanzo.ai/v1/chat/completions \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "zen6",
    "messages": [{"role": "user", "content": "Hello, Zen."}]
  }'
```

**CLI**

```bash
hanzo chat completions \
  --model zen6 \
  --messages '[{"role":"user","content":"Hello, Zen."}]'
```

**TypeScript**

```typescript
import { Hanzo } from '@hanzo/ai'

const hanzo = new Hanzo({ secretKey: process.env.HANZO_API_KEY })

const completion = await hanzo.chat.completions.create({
  model: 'zen6',
  messages: [{ role: 'user', content: 'Hello, Zen.' }],
})
console.log(completion.choices[0].message.content)
```

**Python**

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["HANZO_API_KEY"],
    base_url="https://api.hanzo.ai/v1",
)

response = client.chat.completions.create(
    model="zen6",
    messages=[{"role": "user", "content": "Hello, Zen."}]
)
print(response.choices[0].message.content)
```

`/v1/chat/completions` takes and returns the chat-completions JSON shape, which
is why the Python tab is the `openai` client with its base URL moved: any client
already written against that shape works here unchanged. Model ids are not
portable across vendors, though — `zen6` and `enso` exist only here. [The
SDKs](https://docs.hanzo.ai/docs/sdks) covers what each language ships and when to reach past the
chat route into the rest of `/v1`.

## Architecture

```text
┌─────────────────────────────────────────────────────────────┐
│                        HANZO CHAT                           │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │ React Client │  │ Node.js API  │  │    DocumentDB    │  │
│  │              │  │              │  │                  │  │
│  │ - Chat UI    │  │ - REST API   │  │ - Messages       │  │
│  │ - Model Sel  │  │ - WebSocket  │  │ - Conversations  │  │
│  │ - File Upload│  │ - MCP Broker │  │ - Users          │  │
│  │ - Agents     │  │ - Auth       │  │ - Presets        │  │
│  └──────────────┘  └──────────────┘  └──────────────────┘  │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐    │
│  │              Provider Layer (AI API)            │    │
│  │  Zen · OpenAI · Anthropic · Google · Meta · …       │    │
│  └─────────────────────────────────────────────────────┘    │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐    │
│  │  Search       │  KV     │  S3     │  RAG API       │    │
│  └─────────────────────────────────────────────────────┘    │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

## Endpoints

| Environment | URL                       |
| ----------- | ------------------------- |
| Production  | `https://chat.hanzo.ai`   |
| API         | `https://api.hanzo.ai/v1` |
| Local       | `http://localhost:3081`   |

## Pricing

- **$5 free credit** on every new account (expires in 30 days)
- **Prepaid billing** — add credits via [platform.hanzo.ai](https://platform.hanzo.ai)
- **Starting at $0.34/MTok** input (`zen5-flash`)
- **No surprise bills** — service stops when credits are depleted

* [Features](https://docs.hanzo.ai/docs/chat/features): Presets, file uploads, RAG, search, vision, conversation management
* [Configuration](https://docs.hanzo.ai/docs/chat/configuration): chat.yaml reference, endpoints, MCP tools, model config
* [Models](https://docs.hanzo.ai/docs/chat/models): Every model in the menu, with its context window and rate
* [Agents](https://docs.hanzo.ai/docs/chat/agents): Custom AI agents with system prompts and tool access
* [Self-Hosting](https://docs.hanzo.ai/docs/chat/self-hosting): Docker, Kubernetes, and cloud deployment guides
* [Authentication](https://docs.hanzo.ai/docs/chat/authentication): Hanzo IAM, OAuth2, social login, SSO

## In this section

- [Hanzo Dev](https://docs.hanzo.ai/docs/dev): AI-powered coding assistant for your terminal. Install, configure, and operate Hanzo Dev.
- [Integrations](https://docs.hanzo.ai/docs/guides/integrations): Connect blob storage, Slack, Mixpanel, and Insights to your project.
- [Integrations & Extensions](https://docs.hanzo.ai/docs/apps): Install and connect Hanzo across your browser, editor, desktop, docs, design tools, and business apps — one…

- [Features](https://docs.hanzo.ai/docs/chat/features): Hanzo Chat features — presets, file uploads, RAG, search, vision, conversation import/export, bookmarks, and more.
- [Configuration](https://docs.hanzo.ai/docs/chat/configuration): Configure Hanzo Chat — models, endpoints, MCP tools, environment variables, and chat.yaml reference.
- [Models](https://docs.hanzo.ai/docs/chat/models): Which models Hanzo Chat can reach, and how to choose and configure them in chat.yaml.
- [Agents](https://docs.hanzo.ai/docs/chat/agents): Create custom AI agents in Hanzo Chat with system prompts, model selection, and MCP tool access.
- [File Uploads & RAG](https://docs.hanzo.ai/docs/chat/file-uploads): Upload files to Hanzo Chat for context-aware responses using Retrieval-Augmented Generation (RAG).
- [Plugins](https://docs.hanzo.ai/docs/chat/plugins): Hanzo Chat plugin system — built-in plugins, ChatGPT plugins, and custom plugin development.
- [Moderation](https://docs.hanzo.ai/docs/chat/moderation): Automated moderation system for Hanzo Chat — rate limiting, violation tracking, and user bans.
- [Self-Hosting](https://docs.hanzo.ai/docs/chat/self-hosting): Deploy Hanzo Chat with Docker, Kubernetes, or on cloud providers. Full self-hosting guide with production configuration.
- [Authentication](https://docs.hanzo.ai/docs/chat/authentication): Configure authentication for Hanzo Chat — Hanzo IAM, OAuth2/OIDC, social login, and local auth.
- [Environment Variables](https://docs.hanzo.ai/docs/chat/environment): Complete reference for all Hanzo Chat environment variables — server, database, auth, models, moderation, and more.