Hanzo Bot

Bot

Top-level overview of Bot, features, and purpose

Your AI team, deployed everywhere.

Bot

Any OS + WhatsApp/Telegram/Discord/iMessage gateway for AI agents (Pi).
Plugins add Mattermost and more. Send a message, get an agent response — from your pocket.

GitHub · Releases · Docs · Bot assistant setup

Bot bridges WhatsApp (via WhatsApp Web / Baileys), Telegram (Bot API / grammY), Discord (Bot API / channels.discord.js), and iMessage (imsg CLI) to coding agents like Pi. Plugins add Mattermost (Bot API + WebSocket) and more.

Start here

If the Gateway is running on the same computer, that link opens the browser Control UI immediately. If it fails, start the Gateway first: bot gateway.

Dashboard (browser Control UI)

The dashboard is the browser Control UI for chat, config, nodes, sessions, and more. Local default: http://127.0.0.1:18789/ Remote access: Web surfaces and Tailscale

How it works

WhatsApp / Telegram / Discord / iMessage (+ plugins)
        │
        ▼
  ┌───────────────────────────┐
  │          Gateway          │  ws://127.0.0.1:18789 (loopback-only)
  │     (single source)       │
  │                           │  http://gateway-host:18793
  │                           │    /__bot__/canvas/ (Canvas host)
  └───────────┬───────────────┘
              │
              ├─ Pi agent (RPC)
              ├─ CLI (bot …)
              ├─ Chat UI (SwiftUI)
              ├─ macOS app (Bot.app)
              ├─ iOS node via Gateway WS + pairing
              └─ Android node via Gateway WS + pairing

Most operations flow through the Gateway (bot gateway), a single long-running process that owns channel connections and the WebSocket control plane.

Network model

  • One Gateway per host (recommended): it is the only process allowed to own the WhatsApp Web session. If you need a rescue bot or strict isolation, run multiple gateways with isolated profiles and ports; see Multiple gateways.
  • Loopback-first: Gateway WS defaults to ws://127.0.0.1:18789.
    • The wizard now generates a gateway token by default (even for loopback).
    • For Tailnet access, run bot gateway --bind tailnet --token ... (token is required for non-loopback binds).
  • Nodes: connect to the Gateway WebSocket (LAN/tailnet/SSH as needed); legacy TCP bridge is deprecated/removed.
  • Canvas host: HTTP file server on canvasHost.port (default 18793), serving /__bot__/canvas/ for node WebViews; see Gateway configuration (canvasHost).
  • Remote use: SSH tunnel or tailnet/VPN; see Remote access and Discovery.

Features (high level)

  • 📱 WhatsApp Integration — Uses Baileys for WhatsApp Web protocol
  • ✈️ Telegram Bot — DMs + groups via grammY
  • 🎮 Discord Bot — DMs + guild channels via channels.discord.js
  • 🧩 Mattermost Bot (plugin) — Bot token + WebSocket events
  • 💬 iMessage — Local imsg CLI integration (macOS)
  • 🤖 Agent bridge — Pi (RPC mode) with tool streaming
  • ⏱️ Streaming + chunking — Block streaming + Telegram draft streaming details (/concepts/streaming)
  • 🧠 Multi-agent routing — Route provider accounts/peers to isolated agents (workspace + per-agent sessions)
  • 🔐 Subscription auth — Anthropic (Claude Pro/Max) + OpenAI (ChatGPT/Codex) via OAuth
  • 💬 Sessions — Direct chats collapse into shared main (default); groups are isolated
  • 👥 Group Chat Support — Mention-based by default; owner can toggle /activation always|mention
  • 📎 Media Support — Send and receive images, audio, documents
  • 🎤 Voice notes — Optional transcription hook
  • 🖥️ WebChat + macOS app — Local UI + menu bar companion for ops and voice wake
  • 📱 iOS node — Pairs as a node and exposes a Canvas surface
  • 📱 Android node — Pairs as a node and exposes Canvas + Chat + Camera

Note: legacy Claude/Codex/Gemini/Opencode paths have been removed; Pi is the only coding-agent path.

Quick start

Runtime requirement: Node >= 22.

# Recommended: global install (npm/pnpm)
npm install -g bot@latest
# or: pnpm add -g bot@latest

# Onboard + install the service (launchd/systemd user service)
bot onboard --install-daemon

# Pair WhatsApp Web (shows QR)
bot channels login

# Gateway runs via the service after onboarding; manual run is still possible:
bot gateway --port 18789

Switching between npm and git installs later is easy: install the other flavor and run bot doctor to update the gateway service entrypoint.

From source (development):

git clone https://github.com/hanzoai/bot.git
cd bot
pnpm install
pnpm ui:build # auto-installs UI deps on first run
pnpm build
bot onboard --install-daemon

If you don't have a global install yet, run the onboarding step via pnpm bot ... from the repo.

Multi-instance quickstart (optional):

BOT_CONFIG_PATH=~/.bot/a.json \
BOT_STATE_DIR=~/.bot-a \
bot gateway --port 19001

Send a test message (requires a running Gateway):

bot message send --target +15555550123 --message "Hello from Bot"

Configuration (optional)

Config lives at ~/.bot/bot.json.

  • If you do nothing, Bot uses the bundled Pi binary in RPC mode with per-sender sessions.
  • If you want to lock it down, start with channels.whatsapp.allowFrom and (for groups) mention rules.

Example:

{
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } }
    }
  },
  messages: { groupChat: { mentionPatterns: ["@bot"] } }
}

Docs

Credits

  • Hanzo AI (@hanzoai) — Techstars '17, AI infrastructure
  • Peter Steinberger (@steipete) — Creator
  • Mario Zechner (@badlogicc) — Pi creator, security pen-tester

Core Contributors

License

MIT

Last updated on

On this page

Start here
Dashboard (browser Control UI)
How it works
Network model
Features (high level)
Quick start
Configuration (optional)
Docs
Credits
Core Contributors
License