bot/docs/gateway/index.md

summary, read_when, title

summary	read_when	title
Runbook for the Gateway service, lifecycle, and operations	Running or debugging the gateway process	Gateway Runbook

Gateway runbook

Use this page for day-1 startup and day-2 operations of the Gateway service.

Symptom-first diagnostics with exact command ladders and log signatures. Task-oriented setup guide + full configuration reference. SecretRef contract, runtime snapshot behavior, and migrate/reload operations. Exact `secrets apply` target/path rules and ref-only auth-profile behavior.

5-minute local startup

hanzo-bot gateway --port 18789
# debug/trace mirrored to stdio
hanzo-bot gateway --port 18789 --verbose
# force-kill listener on selected port, then start
hanzo-bot gateway --force

hanzo-bot gateway status
hanzo-bot status
hanzo-bot logs --follow

Healthy baseline: Runtime: running and RPC probe: ok.

hanzo-bot channels status --probe

Gateway config reload watches the active config file path (resolved from profile/state defaults, or `BOT_CONFIG_PATH` when set). Default mode is `gateway.reload.mode="hybrid"`.

Runtime model

• One always-on process for routing, control plane, and channel connections.
• Single multiplexed port for:
  • WebSocket control/RPC
  • HTTP APIs (OpenAI-compatible, Responses, tools invoke)
  • Control UI and hooks
• Default bind mode: loopback.
• Auth is required by default (gateway.auth.token / gateway.auth.password, or BOT_GATEWAY_TOKEN / BOT_GATEWAY_PASSWORD).

Port and bind precedence

Setting	Resolution order
Gateway port	--port → BOT_GATEWAY_PORT → gateway.port → 18789
Bind mode	CLI/override → gateway.bind → loopback

Hot reload modes

gateway.reload.mode	Behavior
off	No config reload
hot	Apply only hot-safe changes
restart	Restart on reload-required changes
hybrid (default)	Hot-apply when safe, restart when required

Operator command set

hanzo-bot gateway status
hanzo-bot gateway status --deep
hanzo-bot gateway status --json
hanzo-bot gateway install
hanzo-bot gateway restart
hanzo-bot gateway stop
hanzo-bot secrets reload
hanzo-bot logs --follow
hanzo-bot doctor

Remote access

Preferred: Tailscale/VPN. Fallback: SSH tunnel.

ssh -N -L 18789:127.0.0.1:18789 user@host

Then connect clients to ws://127.0.0.1:18789 locally.

If gateway auth is configured, clients still must send auth (`token`/`password`) even over SSH tunnels.

See: Remote Gateway, Authentication, Tailscale.

Supervision and service lifecycle

Use supervised runs for production-like reliability.

hanzo-bot gateway install
hanzo-bot gateway status
hanzo-bot gateway restart
hanzo-bot gateway stop

LaunchAgent labels are ai.hanzo.bot.gateway (default) or ai.hanzo.bot.<profile> (named profile). hanzo-bot doctor audits and repairs service config drift.

hanzo-bot gateway install
systemctl --user enable --now hanzo-bot-gateway[-<profile>].service
hanzo-bot gateway status

For persistence after logout, enable lingering:

sudo loginctl enable-linger <user>

Use a system unit for multi-user/always-on hosts.

sudo systemctl daemon-reload
sudo systemctl enable --now hanzo-bot-gateway[-<profile>].service

Multiple gateways on one host

Most setups should run one Gateway. Use multiple only for strict isolation/redundancy (for example a rescue profile).

Checklist per instance:

• Unique gateway.port
• Unique BOT_CONFIG_PATH
• Unique BOT_STATE_DIR
• Unique agents.defaults.workspace

Example:

BOT_CONFIG_PATH=~/.bot/a.json BOT_STATE_DIR=~/.bot-a hanzo-bot gateway --port 19001
BOT_CONFIG_PATH=~/.bot/b.json BOT_STATE_DIR=~/.bot-b hanzo-bot gateway --port 19002

See: Multiple gateways.

Dev profile quick path

hanzo-bot --dev setup
hanzo-bot --dev gateway --allow-unconfigured
hanzo-bot --dev status

Defaults include isolated state/config and base gateway port 19001.

Protocol quick reference (operator view)

• First client frame must be connect.
• Gateway returns hello-ok snapshot (presence, health, stateVersion, uptimeMs, limits/policy).
• Requests: req(method, params) → res(ok/payload|error).
• Common events: connect.challenge, agent, chat, presence, tick, health, heartbeat, shutdown.

Agent runs are two-stage:

1. Immediate accepted ack (status:"accepted")
2. Final completion response (status:"ok"|"error"), with streamed agent events in between.

See full protocol docs: Gateway Protocol.

Operational checks

Liveness

• Open WS and send connect.
• Expect hello-ok response with snapshot.

Readiness

hanzo-bot gateway status
hanzo-bot channels status --probe
hanzo-bot health

Gap recovery

Events are not replayed. On sequence gaps, refresh state (health, system-presence) before continuing.

Common failure signatures

Signature	Likely issue
refusing to bind gateway ... without auth	Non-loopback bind without token/password
another gateway instance is already listening / EADDRINUSE	Port conflict
Gateway start blocked: set gateway.mode=local	Config set to remote mode
unauthorized during connect	Auth mismatch between client and gateway

For full diagnosis ladders, use Gateway Troubleshooting.

Safety guarantees

• Gateway protocol clients fail fast when Gateway is unavailable (no implicit direct-channel fallback).
• Invalid/non-connect first frames are rejected and closed.
• Graceful shutdown emits shutdown event before socket close.

---

Related:

• Troubleshooting
• Background Process
• Configuration
• Health
• Doctor
• Authentication