zeekay
6e661b15d3
- Rename lobster extension → flow (dir, types, env vars, docs) - LOBSTER_* env vars → BOT_FLOW_* / BOT_* - 🦞 → 🤖 everywhere (src, docs, skills, zh-CN) - docs.bot.ai → docs.hanzo.bot - github.com/bot/bot → github.com/hanzoai/bot - @bot/* → @hanzo/bot-* (npm scope) - ~/.bot/ → ~/.hanzo/bot/ (config paths) - discord.gg/hanzo → discord.gg/XthHQQj (real Hanzo Discord) - clawhub.com → skills.hanzo.bot - ClawDock → BotDock in shell helpers - EXFOLIATE lore → Hanzo Bot branding in all locales - LOBSTER_PALETTE → BOT_PALETTE, LOBSTER_ASCII → BOT_ASCII
5.2 KiB
BotDock
Stop typing docker-compose commands. Just type bot-start.
Inspired by Simon Willison's Running Hanzo Bot in Docker.
Quickstart
Install:
mkdir -p ~/.bot && curl -sL https://raw.githubusercontent.com/hanzoai/bot/main/scripts/shell-helpers/bot-helpers.sh -o ~/.hanzo/bot/bot-helpers.sh
echo 'source ~/.hanzo/bot/bot-helpers.sh' >> ~/.zshrc && source ~/.zshrc
See what you get:
bot-help
On first command, BotDock auto-detects your Hanzo Bot directory:
- Checks common paths (
~/hanzo-bot,~/workspace/hanzo-bot, etc.) - If found, asks you to confirm
- Saves to
~/.hanzo/bot/config
First time setup:
bot-start
bot-fix-token
bot-dashboard
If you see "pairing required":
bot-devices
And approve the request for the specific device:
bot-approve <request-id>
Available Commands
Basic Operations
| Command | Description |
|---|---|
bot-start |
Start the gateway |
bot-stop |
Stop the gateway |
bot-restart |
Restart the gateway |
bot-status |
Check container status |
bot-logs |
View live logs (follows output) |
Container Access
| Command | Description |
|---|---|
bot-shell |
Interactive shell inside the gateway container |
bot-cli <command> |
Run Hanzo Bot CLI commands |
bot-exec <command> |
Execute arbitrary commands in the container |
Web UI & Devices
| Command | Description |
|---|---|
bot-dashboard |
Open web UI in browser with authentication |
bot-devices |
List device pairing requests |
bot-approve <id> |
Approve a device pairing request |
Setup & Configuration
| Command | Description |
|---|---|
bot-fix-token |
Configure gateway authentication token (run once) |
Maintenance
| Command | Description |
|---|---|
bot-rebuild |
Rebuild the Docker image |
bot-clean |
Remove all containers and volumes (destructive!) |
Utilities
| Command | Description |
|---|---|
bot-health |
Run gateway health check |
bot-token |
Display the gateway authentication token |
bot-cd |
Jump to the Hanzo Bot project directory |
bot-config |
Open the Hanzo Bot config directory |
bot-workspace |
Open the workspace directory |
bot-help |
Show all available commands with examples |
Common Workflows
Check Status and Logs
Restart the gateway:
bot-restart
Check container status:
bot-status
View live logs:
bot-logs
Set Up WhatsApp Bot
Shell into the container:
bot-shell
Inside the container, login to WhatsApp:
hanzo-bot channels login --channel whatsapp --verbose
Scan the QR code with WhatsApp on your phone.
Verify connection:
hanzo-bot status
Troubleshooting Device Pairing
Check for pending pairing requests:
bot-devices
Copy the Request ID from the "Pending" table, then approve:
bot-approve <request-id>
Then refresh your browser.
Fix Token Mismatch Issues
If you see "gateway token mismatch" errors:
bot-fix-token
This will:
- Read the token from your
.envfile - Configure it in the Hanzo Bot config
- Restart the gateway
- Verify the configuration
Permission Denied
Ensure Docker is running and you have permission:
docker ps
Requirements
- Docker and Docker Compose installed
- Bash or Zsh shell
- Hanzo Bot project (from
docker-setup.sh)
Development
Test with fresh config (mimics first-time install):
unset BOTDOCK_DIR && rm -f ~/.hanzo/bot/config && source scripts/shell-helpers/bot-helpers.sh
Then run any command to trigger auto-detect:
bot-start