troubleshootinglisted

# Troubleshooting Reference guide for diagnosing errors. Read this when a command fails, a bridge is unreachable, or a user reports something isn't working. ## When to Use - A `host_execute` call returns an error - Claude Code mode fails - User says something "doesn't work" or asks how to set up a feature - You get connection, auth, or permission errors ## Gateway Errors ### "Cannot connect to host gateway. Is the gateway server running?" The gateway process is not running on the host machine. **Tell the user:** Run `make gateway` on the host (outside Docker) to start it. ### "Gateway auth failed. Check GATEWAY_TOKEN." The token in the Docker container doesn't match the one on the host. **Tell the user:** Verify that `GATEWAY_TOKEN` in `.env` matches on both sides, then restart both gateway and container. ### "unknown bridge 'X'. Available: ..." The bridge name doesn't exist in `config.yaml` under `gateway.bridges`. **Check:** Are you using the correct bridge name? Compare with the available list in the error. ### "command 'X' not allowed for bridge 'Y'" The CLI command is not in the bridge's `allowed_commands` list. This is a security feature. **Tell the user:** Add the command to the bridge's `allowed_commands` in `config.yaml` and restart the gateway. ## CLI Not Found ### "Command 'X' not found on host. Install it first." The CLI binary is not installed on the host. Exit code 127. **Installation commands (Homebrew):** | CLI | Install command | |-----|-