mirror of
https://github.com/hanzoai/bot.git
synced 2026-10-30 17:24:26 +00:00
zooqueen
071e3f1082
Automated rebrand of all openclaw references to hanzo bot: - Package: openclaw -> @hanzo/bot - Binary: openclaw -> hanzo-bot - Config: ~/.openclaw -> ~/.hanzo/bot - Docker: ghcr.io/hanzoai/bot - Env vars: OPENCLAW_* -> BOT_* - Bundle IDs: ai.hanzo.bot.* - Product name: Hanzo Bot
1.6 KiB
1.6 KiB
summary, read_when, title
| summary | read_when | title | ||
|---|---|---|---|---|
| Gateway singleton guard using the WebSocket listener bind |
|
Gateway Lock |
Gateway lock
Last updated: 2025-12-11
Why
- Ensure only one gateway instance runs per base port on the same host; additional gateways must use isolated profiles and unique ports.
- Survive crashes/SIGKILL without leaving stale lock files.
- Fail fast with a clear error when the control port is already occupied.
Mechanism
- The gateway binds the WebSocket listener (default
ws://127.0.0.1:18789) immediately on startup using an exclusive TCP listener. - If the bind fails with
EADDRINUSE, startup throwsGatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>"). - The OS releases the listener automatically on any process exit, including crashes and SIGKILL—no separate lock file or cleanup step is needed.
- On shutdown the gateway closes the WebSocket server and underlying HTTP server to free the port promptly.
Error surface
- If another process holds the port, startup throws
GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>"). - Other bind failures surface as
GatewayLockError("failed to bind gateway socket on ws://127.0.0.1:<port>: …").
Operational notes
- If the port is occupied by another process, the error is the same; free the port or choose another with
hanzo-bot gateway --port <port>. - The macOS app still maintains its own lightweight PID guard before spawning the gateway; the runtime lock is enforced by the WebSocket bind.