Frequently asked questions about Bot setup, configuration, and usage
Quick answers plus deeper troubleshooting for real-world setups (local dev, VPS, multi-agent, OAuth/API keys, model failover). For runtime diagnostics, see Troubleshooting. For the full config reference, see Configuration.
Use a local AI agent that can see your machine. That is far more effective than asking
in Discord, because most "I'm stuck" cases are local config or environment issues that
remote helpers cannot inspect.
These tools can read the repo, run commands, inspect logs, and help fix your machine-level
setup (PATH, services, permissions, auth files). Give them the full source checkout via
the hackable (git) install:
This installs Bot from a git checkout, so the agent can read the code + docs and
reason about the exact version you are running. You can always switch back to stable later
by re-running the installer without --install-method git.
Tip: ask the agent to plan and supervise the fix (step-by-step), then execute only the
necessary commands. That keeps changes small and easier to audit.
The wizard now opens your browser with a tokenized dashboard URL right after onboarding and also prints the full link (with token) in the summary. Keep that tab open; if it didn’t launch, copy/paste the printed URL on the same machine. Tokens stay local to your host-nothing is fetched from the browser.
If it asks for auth, run bot dashboard and use the tokenized link (?token=...).
The token is the same value as gateway.auth.token (or BOT_GATEWAY_TOKEN) and is stored by the UI after first load.
Not on localhost:
Tailscale Serve (recommended): keep bind loopback, run bot gateway --tailscale serve, open https://<magicdns>/. If gateway.auth.allowTailscale is true, identity headers satisfy auth (no token).
Tailnet bind: run bot gateway --bind tailnet --token "<token>", open http://<tailscale-ip>:18789/, paste token in dashboard settings.
SSH tunnel: ssh -N -L 18789:127.0.0.1:18789 user@host then open http://127.0.0.1:18789/?token=... from bot dashboard.
Yes. The Gateway is lightweight - docs list 512MB-1GB RAM, 1 core, and about 500MB
disk as enough for personal use, and note that a Raspberry Pi 4 can run it.
If you want extra headroom (logs, media, other services), 2GB is recommended, but it’s
not a hard minimum.
Tip: a small Pi/VPS can host the Gateway, and you can pair nodes on your laptop/phone for
local screen/camera/canvas or command execution. See Nodes.
That screen depends on the Gateway being reachable and authenticated. The TUI also sends
"Wake up, my friend!" automatically on first hatch. If you see that line with no reply
and tokens stay at 0, the agent never ran.
Restart the Gateway:
bot gateway restart
Check status + auth:
bot statusbot models statusbot logs --follow
If it still hangs, run:
bot doctor
If the Gateway is remote, ensure the tunnel/Tailscale connection is up and that the UI
is pointed at the right Gateway. See Remote access.
Yes. Copy the state directory and workspace, then run Doctor once. This
keeps your bot “exactly the same” (memory, session history, auth, and channel
state) as long as you copy both locations:
Install Bot on the new machine.
Copy $BOT_STATE_DIR (default: ~/.bot) from the old machine.
Copy your workspace (default: ~/bot).
Run bot doctor and restart the Gateway service.
That preserves config, auth profiles, WhatsApp creds, sessions, and memory. If you’re in
remote mode, remember the gateway host owns the session store and workspace.
Important: if you only commit/push your workspace to GitHub, you’re backing
up memory + bootstrap files, but not session history or auth. Those live
under ~/.bot/ (for example ~/.bot/agents/<agentId>/sessions/).
Newest entries are at the top. If the top section is marked Unreleased, the next dated
section is the latest shipped version. Entries are grouped by Highlights, Changes, and
Fixes (plus docs/other sections when needed).
Some Comcast/Xfinity connections incorrectly block docs.hanzo.bot via Xfinity
Advanced Security. Disable it or allowlist docs.hanzo.bot, then retry. More
detail: Troubleshooting.
Please help us unblock it by reporting here: https://spa.xfinity.com/check_url_status.
Stable and beta are npm dist‑tags, not separate code lines:
latest = stable
beta = early build for testing
We ship builds to beta, test them, and once a build is solid we promote
that same version to latest. That’s why beta and stable can point at the
same version.
Use the hackable (git) install so you have the full source and docs locally, then ask
your bot (or Claude/Codex) from that folder so it can read the repo and answer precisely.
How it works in the cloud: the Gateway runs on the server, and you access it
from your laptop/phone via the Control UI (or Tailscale/SSH). Your state + workspace
live on the server, so treat the host as the source of truth and back it up.
You can pair nodes (Mac/iOS/Android/headless) to that cloud Gateway to access
local screen/camera/canvas or run commands on your laptop while keeping the
Gateway in the cloud.
Short answer: possible, not recommended. The update flow can restart the
Gateway (which drops the active session), may need a clean git checkout, and
can prompt for confirmation. Safer: run updates from a shell as the operator.
bot onboard is the recommended setup path. In local mode it walks you through:
Model/auth setup (Anthropic setup-token recommended for Claude subscriptions, OpenAI Codex OAuth supported, API keys optional, LM Studio local models supported)
No. You can run Bot with API keys (Anthropic/OpenAI/others) or with
local‑only models so your data stays on your device. Subscriptions (Claude
Pro/Max or OpenAI Codex) are optional ways to authenticate those providers.
Yes. You can authenticate with Claude Code CLI OAuth or a setup-token
instead of an API key. This is the subscription path.
Claude Pro/Max subscriptions do not include an API key, so this is the
correct approach for subscription accounts. Important: you must verify with
Anthropic that this usage is allowed under their subscription policy and terms.
If you want the most explicit, supported path, use an Anthropic API key.
claude setup-token generates a token string via the Claude Code CLI (it is not available in the web console). You can run it on any machine. If Claude Code CLI credentials are present on the gateway host, Bot can reuse them; otherwise choose Anthropic token (paste setup-token) and paste the string. The token is stored as an auth profile for the anthropic provider and used like an API key or OAuth profile. More detail: OAuth.
Bot keeps auth.profiles["anthropic:claude-cli"].mode set to "oauth" so
the profile accepts both OAuth and setup-token credentials; older "token" mode
entries auto-migrate.
It is not in the Anthropic Console. The setup-token is generated by the Claude Code CLI on any machine:
claude setup-token
Copy the token it prints, then choose Anthropic token (paste setup-token) in the wizard. If you want to run it on the gateway host, use bot models auth setup-token --provider anthropic. If you ran claude setup-token elsewhere, paste it on the gateway host with bot models auth paste-token --provider anthropic. See Anthropic.
Yes. Bot can reuse Claude Code CLI credentials (OAuth) and also supports setup-token. If you have a Claude subscription, we recommend setup-token for long‑running setups (requires Claude Pro/Max + the claude CLI). You can generate it anywhere and paste it on the gateway host. OAuth reuse is supported, but avoid logging in separately via Bot and Claude Code to prevent token conflicts. See Anthropic and OAuth.
Note: Claude subscription access is governed by Anthropic’s terms. For production or multi‑user workloads, API keys are usually the safer choice.
That means your Anthropic quota/rate limit is exhausted for the current window. If you
use a Claude subscription (setup‑token or Claude Code OAuth), wait for the window to
reset or upgrade your plan. If you use an Anthropic API key, check the Anthropic Console
for usage/billing and raise limits as needed.
Tip: set a fallback model so Bot can keep replying while a provider is rate‑limited.
See Models and OAuth.
Yes - via pi‑ai’s Amazon Bedrock (Converse) provider with manual config. You must supply AWS credentials/region on the gateway host and add a Bedrock provider entry in your models config. See Amazon Bedrock and Model providers. If you prefer a managed key flow, an OpenAI‑compatible proxy in front of Bedrock is still a valid option.
Bot supports OpenAI Code (Codex) via OAuth or by reusing your Codex CLI login (~/.codex/auth.json). The wizard can import the CLI login or run the OAuth flow and will set the default model to openai-codex/gpt-5.2 when appropriate. See Model providers and Wizard.
Yes. Bot fully supports OpenAI Code (Codex) subscription OAuth and can also reuse an
existing Codex CLI login (~/.codex/auth.json) on the gateway host. The onboarding wizard
can import the CLI login or run the OAuth flow for you.
Usually no. Bot needs large context + strong safety; small cards truncate and leak. If you must, run the largest MiniMax M2.1 build you can locally (LM Studio) and see /gateway/local-models. Smaller/quantized models increase prompt-injection risk - see Security.
Pick region-pinned endpoints. OpenRouter exposes US-hosted options for MiniMax, Kimi, and GLM; choose the US-hosted variant to keep data in-region. You can still list Anthropic/OpenAI alongside these by using models.mode: "merge" so fallbacks stay available while respecting the regioned provider you select.
No. Bot runs on macOS or Linux (Windows via WSL2). A Mac mini is optional - some people
buy one as an always‑on host, but a small VPS, home server, or Raspberry Pi‑class box works too.
You only need a Mac for macOS‑only tools. For iMessage, you can keep the Gateway on Linux
and run imsg on any Mac over SSH by pointing channels.imessage.cliPath at an SSH wrapper.
If you want other macOS‑only tools, run the Gateway on a Mac or pair a macOS node.
You need some macOS device signed into Messages. It does not have to be a Mac mini -
any Mac works. Bot’s iMessage integrations run on macOS (BlueBubbles or imsg), while
the Gateway can run elsewhere.
Common setups:
Run the Gateway on Linux/VPS, and point channels.imessage.cliPath at an SSH wrapper that
runs imsg on the Mac.
Run everything on the Mac if you want the simplest single‑machine setup.
Yes. The Mac mini can run the Gateway, and your MacBook Pro can connect as a
node (companion device). Nodes don’t run the Gateway - they provide extra
capabilities like screen/camera/canvas and system.run on that device.
Common pattern:
Gateway on the Mac mini (always‑on).
MacBook Pro runs the macOS app or a node host and pairs to the Gateway.
Yes, via multi‑agent routing. Bind each sender’s WhatsApp DM (peer kind: "dm", sender E.164 like +15551234567) to a different agentId, so each person gets their own workspace and session store. Replies still come from the same WhatsApp account, and DM access control (channels.whatsapp.dmPolicy / channels.whatsapp.allowFrom) is global per WhatsApp account. See Multi-Agent Routing and WhatsApp.
Yes. Use multi‑agent routing: give each agent its own default model, then bind inbound routes (provider account or specific peers) to each agent. Example config lives in Multi-Agent Routing. See also Models and Configuration.
If you run Bot via systemd, ensure the service PATH includes /home/linuxbrew/.linuxbrew/bin (or your brew prefix) so brew-installed tools resolve in non‑login shells.
Recent builds also prepend common user bin dirs on Linux systemd services (for example ~/.local/bin, ~/.npm-global/bin, ~/.local/share/pnpm, ~/.bun/bin) and honor PNPM_HOME, NPM_CONFIG_PREFIX, BUN_INSTALL, VOLTA_HOME, ASDF_DATA_DIR, NVM_DIR, and FNM_DIR when set.
Yes. Install the other flavor, then run Doctor so the gateway service points at the new entrypoint.
This does not delete your data - it only changes the Bot code install. Your state
(~/.bot) and workspace (~/bot) stay untouched.
Doctor detects a gateway service entrypoint mismatch and offers to rewrite the service config to match the current install (use --repair in automation).
Short answer: if you want 24/7 reliability, use a VPS. If you want the
lowest friction and you’re okay with sleep/restarts, run it locally.
Laptop (local Gateway)
Pros: no server cost, direct access to local files, live browser window.
Cons: sleep/network drops = disconnects, OS updates/reboots interrupt, must stay awake.
VPS / cloud
Pros: always‑on, stable network, no laptop sleep issues, easier to keep running.
Cons: often run headless (use screenshots), remote file access only, you must SSH for updates.
Bot-specific note: WhatsApp/Telegram/Slack/Mattermost (plugin)/Discord all work fine from a VPS. The only real trade-off is headless browser vs a visible window. See Browser.
Recommended default: VPS if you had gateway disconnects before. Local is great when you’re actively using the Mac and want local file access or UI automation with a visible browser.
Shared laptop/desktop: totally fine for testing and active use, but expect pauses when the machine sleeps or updates.
If you want the best of both worlds, keep the Gateway on a dedicated host and pair your laptop as a node for local screen/camera/exec tools. See Nodes.
For security guidance, read Security.
Yes. Treat a VM the same as a VPS: it needs to be always on, reachable, and have enough
RAM for the Gateway and any channels you enable.
Baseline guidance:
Absolute minimum: 1 vCPU, 1GB RAM.
Recommended: 2GB RAM or more if you run multiple channels, browser automation, or media tools.
OS: Ubuntu LTS or another modern Debian/Ubuntu.
If you are on Windows, WSL2 is the easiest VM style setup and has the best tooling
compatibility. See Windows, VPS hosting.
If you are running macOS in a VM, see macOS VM.
Bot is a personal AI assistant you run on your own devices. It replies on the messaging surfaces you already use (WhatsApp, Telegram, Slack, Mattermost (plugin), Discord, Google Chat, Signal, iMessage, WebChat) and can also do voice + a live Canvas on supported platforms. The Gateway is the always-on control plane; the assistant is the product.
Bot is not “just a Claude wrapper.” It’s a local-first control plane that lets you run a
capable assistant on your own hardware, reachable from the chat apps you already use, with
stateful sessions, memory, and tools - without handing control of your workflows to a hosted
SaaS.
Highlights:
Your devices, your data: run the Gateway wherever you want (Mac, Linux, VPS) and keep the
workspace + session history local.
Real channels, not a web sandbox: WhatsApp/Telegram/Slack/Discord/Signal/iMessage/etc,
plus mobile voice and Canvas on supported platforms.
Model-agnostic: use Anthropic, OpenAI, MiniMax, OpenRouter, etc., with per‑agent routing
and failover.
Local-only option: run local models so all data can stay on your device if you want.
Multi-agent routing: separate agents per channel, account, or task, each with its own
workspace and defaults.
Open source and hackable: inspect, extend, and self-host without vendor lock‑in.
Yes for research, qualification, and drafting. It can scan sites, build shortlists,
summarize prospects, and write outreach or ad copy drafts.
For outreach or ad runs, keep a human in the loop. Avoid spam, follow local laws and
platform policies, and review anything before it is sent. The safest pattern is to let
Bot draft and you approve.
Bot is a personal assistant and coordination layer, not an IDE replacement. Use
Claude Code or Codex for the fastest direct coding loop inside a repo. Use Bot when you
want durable memory, cross-device access, and tool orchestration.
Use managed overrides instead of editing the repo copy. Put your changes in ~/.bot/skills/<name>/SKILL.md (or add a folder via skills.load.extraDirs in ~/.bot/bot.json). Precedence is <workspace>/skills > ~/.bot/skills > bundled, so managed overrides win without touching git. Only upstream-worthy edits should live in the repo and go out as PRs.
Yes. Add extra directories via skills.load.extraDirs in ~/.bot/bot.json (lowest precedence). Default precedence remains: <workspace>/skills → ~/.bot/skills → bundled → skills.load.extraDirs. skills installs into ./skills by default, which Bot treats as <workspace>/skills.
Use sub-agents for long or parallel tasks. Sub-agents run in their own session,
return a summary, and keep your main chat responsive.
Ask your bot to "spawn a sub-agent for this task" or use /subagents.
Use /status in chat to see what the Gateway is doing right now (and whether it is busy).
Token tip: long tasks and sub-agents both consume tokens. If cost is a concern, set a
cheaper model for sub-agents via agents.defaults.subagents.model.
Not directly. macOS skills are gated by metadata.bot.os plus required binaries, and skills only appear in the system prompt when they are eligible on the Gateway host. On Linux, darwin-only skills (like imsg, apple-notes, apple-reminders) will not load unless you override the gating.
You have three supported patterns:
Option A - run the Gateway on a Mac (simplest).
Run the Gateway where the macOS binaries exist, then connect from Linux in remote mode or over Tailscale. The skills load normally because the Gateway host is macOS.
Option B - use a macOS node (no SSH).
Run the Gateway on Linux, pair a macOS node (menubar app), and set Node Run Commands to "Always Ask" or "Always Allow" on the Mac. Bot can treat macOS-only skills as eligible when the required binaries exist on the node. The agent runs those skills via the nodes tool. If you choose "Always Ask", approving "Always Allow" in the prompt adds that command to the allowlist.
Option C - proxy macOS binaries over SSH (advanced).
Keep the Gateway on Linux, but make the required CLI binaries resolve to SSH wrappers that run on a Mac. Then override the skill to allow Linux so it stays eligible.
Create an SSH wrapper for the binary (example: imsg):
Custom skill / plugin: best for reliable API access (Notion/HeyGen both have APIs).
Browser automation: works without code but is slower and more fragile.
If you want to keep context per client (agency workflows), a simple pattern is:
One Notion page per client (context + preferences + active work).
Ask the agent to fetch that page at the start of a session.
If you want a native integration, open a feature request or build a skill
targeting those APIs.
Install skills:
skills install <skill-slug>skills update --all
Skills installs into ./skills under your current directory (or falls back to your configured Bot workspace); Bot treats that as <workspace>/skills on the next session. For shared skills across agents, place them in ~/.bot/skills/<name>/SKILL.md. Some skills expect binaries installed via Homebrew; on Linux that means Linuxbrew (see the Homebrew Linux FAQ entry above). See Skills and Skills.
Then Chrome → chrome://extensions → enable “Developer mode” → “Load unpacked” → pick that folder.
Full guide (including remote Gateway via Tailscale + security notes): Chrome extension
If the Gateway runs on the same machine as Chrome (default setup), you usually do not need bot browser serve.
You still need to click the extension button on the tab you want to control (it doesn’t auto-attach).
Yes. See Sandboxing. For Docker-specific setup (full gateway in Docker or sandbox images), see Docker.
Can I keep DMs personal but make groups public sandboxed with one agent
Yes - if your private traffic is DMs and your public traffic is groups.
Use agents.defaults.sandbox.mode: "non-main" so group/channel sessions (non-main keys) run in Docker, while the main DM session stays on-host. Then restrict what tools are available in sandboxed sessions via tools.sandbox.tools.
Set agents.defaults.sandbox.docker.binds to ["host:path:mode"] (e.g., "/home/user/src:/src:ro"). Global + per-agent binds merge; per-agent binds are ignored when scope: "shared". Use :ro for anything sensitive and remember binds bypass the sandbox filesystem walls. See Sandboxing and Sandbox vs Tool Policy vs Elevated for examples and safety notes.
Bot memory is just Markdown files in the agent workspace:
Daily notes in memory/YYYY-MM-DD.md
Curated long-term notes in MEMORY.md (main/private sessions only)
Bot also runs a silent pre-compaction memory flush to remind the model
to write durable notes before auto-compaction. This only runs when the workspace
is writable (read-only sandboxes skip it). See Memory.
Ask the bot to write the fact to memory. Long-term notes belong in MEMORY.md,
short-term context goes into memory/YYYY-MM-DD.md.
This is still an area we are improving. It helps to remind the model to store memories;
it will know what to do. If it keeps forgetting, verify the Gateway is using the same
workspace on every run.
Only if you use OpenAI embeddings. Codex OAuth covers chat/completions and
does not grant embeddings access, so signing in with Codex (OAuth or the
Codex CLI login) does not help for semantic memory search. OpenAI embeddings
still need a real API key (OPENAI_API_KEY or models.providers.openai.apiKey).
If you don’t set a provider explicitly, Bot auto-selects a provider when it
can resolve an API key (auth profiles, models.providers.*.apiKey, or env vars).
It prefers OpenAI if an OpenAI key resolves, otherwise Gemini if a Gemini key
resolves. If neither key is available, memory search stays disabled until you
configure it. If you have a local model path configured and present, Bot
prefers local.
If you’d rather stay local, set memorySearch.provider = "local" (and optionally
memorySearch.fallback = "none"). If you want Gemini embeddings, set
memorySearch.provider = "gemini" and provide GEMINI_API_KEY (or
memorySearch.remote.apiKey). We support OpenAI, Gemini, or local embedding
models - see Memory for the setup details.
Memory files live on disk and persist until you delete them. The limit is your
storage, not the model. The session context is still limited by the model
context window, so long conversations can compact or truncate. That is why
memory search exists - it pulls only the relevant parts back into context.
No - Bot’s state is local, but external services still see what you send them.
Local by default: sessions, memory files, config, and workspace live on the Gateway host
(~/.bot + your workspace directory).
Remote by necessity: messages you send to model providers (Anthropic/OpenAI/etc.) go to
their APIs, and chat platforms (WhatsApp/Telegram/Slack/etc.) store message data on their
servers.
You control the footprint: using local models keeps prompts on your machine, but channel
traffic still goes through the channel’s servers.
State dir (~/.bot): config, credentials, auth profiles, sessions, logs,
and shared skills (~/.bot/skills).
Default workspace is ~/bot, configurable via:
{ agents: { defaults: { workspace: "~/bot" } }}
If the bot “forgets” after a restart, confirm the Gateway is using the same
workspace on every launch (and remember: remote mode uses the gateway host’s
workspace, not your local laptop).
Tip: if you want a durable behavior or preference, ask the bot to write it into
AGENTS.md or MEMORY.md rather than relying on chat history.
Put your agent workspace in a private git repo and back it up somewhere
private (for example GitHub private). This captures memory + AGENTS/SOUL/USER
files, and lets you restore the assistant’s “mind” later.
Do not commit anything under ~/.bot (credentials, sessions, tokens).
If you need a full restore, back up both the workspace and the state directory
separately (see the migration question above).
Yes. The workspace is the default cwd and memory anchor, not a hard sandbox.
Relative paths resolve inside the workspace, but absolute paths can access other
host locations unless sandboxing is enabled. If you need isolation, use
agents.defaults.sandbox or per‑agent sandbox settings. If you
want a repo to be the default working directory, point that agent’s
workspace to the repo root. The Bot repo is just source code; keep the
workspace separate unless you intentionally want the agent to work inside it.
Session state is owned by the gateway host. If you’re in remote mode, the session store you care about is on the remote machine, not your local laptop. See Session management.
The wizard generates a gateway token by default (even on loopback) so local WS clients must authenticate. This blocks other local processes from calling the Gateway. Paste the token into the Control UI settings (or your client config) to connect.
If you really want open loopback, remove gateway.auth from your config. Doctor can generate a token for you any time: bot doctor --generate-gateway-token.
web_fetch works without an API key. web_search requires a Brave Search API
key. Recommended: run bot configure --section web to store it in
tools.web.search.apiKey. Environment alternative: set BRAVE_API_KEY for the
Gateway process.
Telegram messages are handled by the gateway. The gateway runs the agent and
only then calls nodes over the Gateway WebSocket when a node tool is needed:
Short answer: pair your computer as a node. The Gateway runs elsewhere, but it can
call node.* tools (screen, camera, system) on your local machine over the Gateway WebSocket.
Typical setup:
Run the Gateway on the always‑on host (VPS/home server).
Put the Gateway host + your computer on the same tailnet.
Ensure the Gateway WS is reachable (tailnet bind or SSH tunnel).
Open the macOS app locally and connect in Remote over SSH mode (or direct tailnet)
so it can register as a node.
Approve the node on the Gateway:
bot nodes pendingbot nodes approve <requestId>
No separate TCP bridge is required; nodes connect over the Gateway WebSocket.
Security reminder: pairing a macOS node allows system.run on that machine. Only
pair devices you trust, and review Security.
Yes. There is no built-in "bot-to-bot" bridge, but you can wire it up in a few
reliable ways:
Simplest: use a normal chat channel both bots can access (Telegram/Slack/WhatsApp).
Have Bot A send a message to Bot B, then let Bot B reply as usual.
CLI bridge (generic): run a script that calls the other Gateway with
bot agent --message ... --deliver, targeting a chat where the other bot
listens. If one bot is on Railway/VPS, point your CLI at that remote Gateway
via SSH/Tailscale (see Remote access).
Example pattern (run from a machine that can reach the target Gateway):
bot agent --message "Hello from local bot" --deliver --channel telegram --reply-to <chat-id>
Tip: add a guardrail so the two bots do not loop endlessly (mention-only, channel
allowlists, or a "do not reply to bot messages" rule).
No. One Gateway can host multiple agents, each with its own workspace, model defaults,
and routing. That is the normal setup and it is much cheaper and simpler than running
one VPS per agent.
Use separate VPSes only when you need hard isolation (security boundaries) or very
different configs that you do not want to share. Otherwise, keep one Gateway and
use multiple agents or sub-agents.
Yes - nodes are the first‑class way to reach your laptop from a remote Gateway, and they
unlock more than shell access. The Gateway runs on macOS/Linux (Windows via WSL2) and is
lightweight (a small VPS or Raspberry Pi-class box is fine; 4 GB RAM is plenty), so a common
setup is an always‑on host plus your laptop as a node.
No inbound SSH required. Nodes connect out to the Gateway WebSocket and use device pairing.
Safer execution controls.system.run is gated by node allowlists/approvals on that laptop.
More device tools. Nodes expose canvas, camera, and screen in addition to system.run.
Local browser automation. Keep the Gateway on a VPS, but run Chrome locally and relay control
with the Chrome extension + bot browser serve.
SSH is fine for ad‑hoc shell access, but nodes are simpler for ongoing agent workflows and
device automation.
If you only need local tools (screen/camera/exec) on the second laptop, add it as a
node. That keeps a single Gateway and avoids duplicated config. Local node tools are
currently macOS-only, but we plan to extend them to other OSes.
Install a second Gateway only when you need hard isolation or two fully separate bots.
No. Only one gateway should run per host unless you intentionally run isolated profiles (see Multiple gateways). Nodes are peripherals that connect
to the gateway (iOS/Android nodes, or macOS “node mode” in the menubar app). For headless node
hosts and CLI control, see Node host CLI.
A full restart is required for gateway, discovery, and canvasHost changes.
This runs your login shell and imports only missing expected keys (never overrides). Env var equivalents:
BOT_LOAD_SHELL_ENV=1, BOT_SHELL_ENV_TIMEOUT_MS=15000.
bot models status reports whether shell env import is enabled. “Shell env: off”
does not mean your env vars are missing - it just means Bot won’t load
your login shell automatically.
If the Gateway runs as a service (launchd/systemd), it won’t inherit your shell
environment. Fix by doing one of these:
Put the token in ~/.bot/.env:
COPILOT_GITHUB_TOKEN=...
Or enable shell import (env.shellEnv.enabled: true).
Or add it to your config env block (applies only if missing).
Yes. Sessions expire after session.idleMinutes (default 60). The next
message starts a fresh session id for that chat key. This does not delete
transcripts - it just starts a new session.
Yes, via multi-agent routing and sub-agents. You can create one coordinator
agent and several worker agents with their own workspaces and models.
That said, this is best seen as a fun experiment. It is token heavy and often
less efficient than using one bot with separate sessions. The typical model we
envision is one bot you talk to, with different sessions for parallel work. That
bot can also spawn sub-agents when needed.
This is a provider validation error: the model emitted a tool_use block without the required
input. It usually means the session history is stale or corrupted (often after long threads
or a tool/schema change).
Fix: start a fresh session with /new (standalone message).
Heartbeats run every 30m by default. Tune or disable them:
{ agents: { defaults: { heartbeat: { every: "2h" // or "0m" to disable } } }}
If HEARTBEAT.md exists but is effectively empty (only blank lines and markdown
headers like # Heading), Bot skips the heartbeat run to save API calls.
If the file is missing, the heartbeat still runs and the model decides what to do.
Per-agent overrides use agents.list[].heartbeat. Docs: Heartbeat.
No. Bot runs on your own account, so if you’re in the group, Bot can see it.
By default, group replies are blocked until you allow senders (groupPolicy: "allowlist").
If you want only you to be able to trigger group replies:
Direct chats collapse to the main session by default. Groups/channels have their own session keys, and Telegram topics / Discord threads are separate sessions. See Groups and Group messages.
Yes. Use Multi‑Agent Routing to run multiple isolated agents and route inbound messages by
channel/account/peer. Slack is supported as a channel and can be bound to specific agents.
Browser access is powerful but not “do anything a human can” - anti‑bot, CAPTCHAs, and MFA can
still block automation. For the most reliable browser control, use the Chrome extension relay
on the machine that runs the browser (and keep the Gateway anywhere).
Best‑practice setup:
Always‑on Gateway host (VPS/Mac mini).
One agent per role (bindings).
Slack channel(s) bound to those agents.
Local browser via extension relay (or a node) when needed.
Models are referenced as provider/model (example: anthropic/claude-opus-4-5). If you omit the provider, Bot currently assumes anthropic as a temporary deprecation fallback - but you should still explicitly set provider/model.
Recommended default:anthropic/claude-opus-4-5. Good alternative:anthropic/claude-sonnet-4-5. Reliable (less character):openai/gpt-5.2 - nearly as good as Opus, just less personality. Budget:zai/glm-4.7.
Rule of thumb: use the best model you can afford for high-stakes work, and a cheaper
model for routine chat or summaries. You can route models per agent and use sub-agents to
parallelize long tasks (each sub-agent consumes tokens). See Models and
Sub-agents.
Strong warning: weaker/over-quantized models are more vulnerable to prompt
injection and unsafe behavior. See Security.
Yes. If your local server exposes an OpenAI-compatible API, you can point a
custom provider at it. Ollama is supported directly and is the easiest path.
Security note: smaller or heavily quantized models are more vulnerable to prompt
injection. We strongly recommend large models for any bot that can use tools.
If you still want small models, enable sandboxing and strict tool allowlists.
Use model commands or edit only the model fields. Avoid full config replaces.
Safe options:
/model in chat (quick, per-session)
bot models set ... (updates just model config)
bot configure --section models (interactive)
edit agents.defaults.model in ~/.bot/bot.json
Avoid config.apply with a partial object unless you intend to replace the whole config.
If you did overwrite config, restore from backup or re-run bot doctor to repair.
Tip: /model status shows which agent is active, which auth-profiles.json file is being used, and which auth profile will be tried next.
It also shows the configured provider endpoint (baseUrl) and API mode (api) when available.
How do I unpin a profile I set with profile
Re-run /modelwithout the @profile suffix:
/model anthropic/claude-opus-4-5
If you want to return to the default, pick it from /model (or send /model <default provider/model>).
Use /model status to confirm which auth profile is active.
Quick switch (per session):/model gpt-5.2 for daily tasks, /model gpt-5.2-codex for coding.
Default + switch: set agents.defaults.model.primary to openai-codex/gpt-5.2, then switch to openai-codex/gpt-5.2-codex when coding (or the other way around).
Sub-agents: route coding tasks to sub-agents with a different default model.
If agents.defaults.models is set, it becomes the allowlist for /model and any
session overrides. Choosing a model that isn’t in that list returns:
Model "provider/model" is not allowed. Use /model to list available models.
That error is returned instead of a normal reply. Fix: add the model to
agents.defaults.models, remove the allowlist, or pick a model from /model list.
This means the provider isn’t configured (no MiniMax provider config or auth
profile was found), so the model can’t be resolved. A fix for this detection is
in 2026.1.12 (unreleased at the time of writing).
Fix checklist:
Upgrade to 2026.1.12 (or run from source main), then restart the gateway.
Make sure MiniMax is configured (wizard or JSON), or that a MiniMax API key
exists in env/auth profiles so the provider can be injected.
Use the exact model id (case‑sensitive): minimax/MiniMax-M2.1 or
minimax/MiniMax-M2.1-lightning.
Yes. Use MiniMax as the default and switch models per session when needed.
Fallbacks are for errors, not “hard tasks,” so use /model or a separate agent.
If you reference a provider/model but the required provider key is missing, you’ll get a runtime auth error (e.g. No API key found for provider "zai").
No API key found for provider after adding a new agent
This usually means the new agent has an empty auth store. Auth is per-agent and
stored in:
~/.bot/agents/<agentId>/agent/auth-profiles.json
Fix options:
Run bot agents add <id> and configure auth during the wizard.
Or copy auth-profiles.json from the main agent’s agentDir into the new agent’s agentDir.
Do not reuse agentDir across agents; it causes auth/session collisions.
If you set ANTHROPIC_API_KEY in your shell but run the Gateway via systemd/launchd, it may not inherit it. Put it in ~/.bot/.env or enable env.shellEnv.
Make sure you’re editing the correct agent
Multi‑agent setups mean there can be multiple auth-profiles.json files.
Sanity‑check model/auth status
Use bot models status to see configured models and whether providers are authenticated.
Fix checklist for No credentials found for profile anthropic claude cli
This means the run is pinned to the Claude Code CLI profile, but the Gateway
can’t find that profile in its auth store.
Sync the Claude Code CLI token on the gateway host
Run bot models status (it loads + syncs Claude Code CLI credentials).
If it still says missing: run claude setup-token (or bot models auth setup-token --provider anthropic) and retry.
If the token was created on another machine
Paste it into the gateway host with bot models auth paste-token --provider anthropic.
Check the profile mode
auth.profiles["anthropic:claude-cli"].mode must be "oauth" (token mode rejects OAuth credentials).
If you want to use an API key instead
Put ANTHROPIC_API_KEY in ~/.bot/.env on the gateway host.
Clear any pinned order that forces anthropic:claude-cli:
bot models auth order clear --provider anthropic
Confirm you’re running commands on the gateway host
In remote mode, auth profiles live on the gateway machine, not your laptop.
If your model config includes Google Gemini as a fallback (or you switched to a Gemini shorthand), Bot will try it during model fallback. If you haven’t configured Google credentials, you’ll see No API key found for provider "google".
Fix: either provide Google auth, or remove/avoid Google models in agents.defaults.model.fallbacks / aliases so fallback doesn’t route there.
LLM request rejected message thinking signature required google antigravity
Cause: the session history contains thinking blocks without signatures (often from
an aborted/partial stream). Google Antigravity requires signatures for thinking blocks.
Fix: Bot now strips unsigned thinking blocks for Google Antigravity Claude. If it still appears, start a new session or set /thinking off for that agent.
Yes. Config supports optional metadata for profiles and an ordering per provider (auth.order.<provider>). This does not store secrets; it maps IDs to provider/mode and sets rotation order.
Bot may temporarily skip a profile if it’s in a short cooldown (rate limits/timeouts/auth failures) or a longer disabled state (billing/insufficient credits). To inspect this, run bot models status --json and check auth.unusableProfiles. Tuning: auth.cooldowns.billingBackoffHours*.
You can also set a per-agent order override (stored in that agent’s auth-profiles.json) via the CLI:
# Defaults to the configured default agent (omit --agent)bot models auth order get --provider anthropic# Lock rotation to a single profile (only try this one)bot models auth order set --provider anthropic anthropic:claude-cli# Or set an explicit order (fallback within provider)bot models auth order set --provider anthropic anthropic:claude-cli anthropic:default# Clear override (fall back to config auth.order / round-robin)bot models auth order clear --provider anthropic
To target a specific agent:
bot models auth order set --provider anthropic --agent main anthropic:claude-cli
Because “running” is the supervisor’s view (launchd/systemd/schtasks). The RPC probe is the CLI actually connecting to the gateway WebSocket and calling status.
Use bot gateway status and trust these lines:
Probe target: (the URL the probe actually used)
Listening: (what’s actually bound on the port)
Last gateway error: (common root cause when the process is alive but the port isn’t listening)
Bot enforces a runtime lock by binding the WebSocket listener immediately on startup (default ws://127.0.0.1:18789). If the bind fails with EADDRINUSE, it throws GatewayLockError indicating another instance is already listening.
Fix: stop the other instance, free the port, or run with bot gateway --port <port>.
tailnet bind picks a Tailscale IP from your network interfaces (100.64.0.0/10). If the machine isn’t on Tailscale (or the interface is down), there’s nothing to bind to.
Fix:
Start Tailscale on that host (so it has a 100.x address), or
Switch to gateway.bind: "loopback" / "lan".
Note: tailnet is explicit. auto prefers loopback; use gateway.bind: "tailnet" when you want a tailnet-only bind.
Usually no - one Gateway can run multiple messaging channels and agents. Use multiple Gateways only when you need redundancy (ex: rescue bot) or hard isolation.
Yes, but you must isolate:
BOT_CONFIG_PATH (per‑instance config)
BOT_STATE_DIR (per‑instance state)
agents.defaults.workspace (workspace isolation)
gateway.port (unique ports)
Quick setup (recommended):
Use bot --profile <name> … per instance (auto-creates ~/.bot-<name>).
Set a unique gateway.port in each profile config (or pass --port for manual runs).
Install a per-profile service: bot --profile <name> gateway install.
Profiles also suffix service names (com.bot.<profile>, bot-gateway-<profile>.service, Bot Gateway (<profile>)).
Full guide: Multiple gateways.
The Gateway is a WebSocket server, and it expects the very first message to
be a connect frame. If it receives anything else, it closes the connection
with code 1008 (policy violation).
Common causes:
You opened the HTTP URL in a browser (http://...) instead of a WS client.
You used the wrong port or path.
A proxy or tunnel stripped auth headers or sent a non‑Gateway request.
Quick fixes:
Use the WS URL: ws://<host>:18789 (or wss://... if HTTPS).
Don’t open the WS port in a normal browser tab.
If auth is on, include the token/password in the connect frame.
If you’re using the CLI or TUI, the URL should look like:
You can set a stable path via logging.file. File log level is controlled by logging.level. Console verbosity is controlled by --verbose and logging.consoleLevel.
Fastest log tail:
bot logs --follow
Service/supervisor logs (when the gateway runs via launchd/systemd):
macOS: $BOT_STATE_DIR/logs/gateway.log and gateway.err.log (default: ~/.bot/logs/...; profiles use ~/.bot-<profile>/logs/...)
If you are on a VPS or behind a proxy, confirm outbound HTTPS is allowed and DNS works.
If the Gateway is remote, make sure you are looking at logs on the Gateway host.
No. Prompt injection is about untrusted content, not just who can DM the bot.
If your assistant reads external content (web search/fetch, browser pages, emails,
docs, attachments, pasted logs), that content can include instructions that try
to hijack the model. This can happen even if you are the only sender.
The biggest risk is when tools are enabled: the model can be tricked into
exfiltrating context or calling tools on your behalf. Reduce the blast radius by:
using a read-only or tool-disabled "reader" agent to summarize untrusted content
keeping web_search / web_fetch / browser off for tool-enabled agents
Yes, for most setups. Isolating the bot with separate accounts and phone numbers
reduces the blast radius if something goes wrong. This also makes it easier to rotate
credentials or revoke access without impacting your personal accounts.
Start small. Give access only to the tools and accounts you actually need, and expand
later if required.
Yes, if the agent is chat-only and the input is trusted. Smaller tiers are
more susceptible to instruction hijacking, so avoid them for tool-enabled agents
or when reading untrusted content. If you must use a smaller model, lock down
tools and run inside a sandbox. See Security.
No. Default WhatsApp DM policy is pairing. Unknown senders only get a pairing code and their message is not processed. Bot only replies to chats it receives or to explicit sends you trigger.
Approve pairing with:
bot pairing approve whatsapp <code>
List pending requests:
bot pairing list whatsapp
Wizard phone number prompt: it’s used to set your allowlist/owner so your own DMs are permitted. It’s not used for auto-sending. If you run on your personal WhatsApp number, use that number and enable channels.whatsapp.selfChatMode.
Most internal or tool messages only appear when verbose or reasoning is enabled
for that session.
Fix in the chat where you see it:
/verbose off/reasoning off
If it is still noisy, check the session settings in the Control UI and set verbose
to inherit. Also confirm you are not using a bot profile with verboseDefault set
to on in config.
Q: “What’s the default model for Anthropic with an API key?”
A: In Bot, credentials and model selection are separate. Setting ANTHROPIC_API_KEY (or storing an Anthropic API key in auth profiles) enables authentication, but the actual default model is whatever you configure in agents.defaults.model.primary (for example, anthropic/claude-sonnet-4-5 or anthropic/claude-opus-4-5). If you see No credentials found for profile "anthropic:default", it means the Gateway couldn’t find Anthropic credentials in the expected auth-profiles.json for the agent that’s running.