Skip to main content

Connect a bot

A bot is an MCP client that Overdeck did not launch: Hermes, OpenClaw, Grok Build, Grok Bot, or a script that calls the xAI API. It uses the same MCP server and tools as everything else, with a token you can scope and revoke. Overdeck has no native Slack, Discord or Telegram bot integration; this page covers MCP clients only. There are two ways in, and both keep the traffic encrypted until it reaches hardware you control:
  • A bot with a shell (Hermes, OpenClaw, Grok Build, Grok Bot) runs the Overdeck connector next to it. The connector pairs with one machine and reaches it over an end-to-end encrypted channel, directly or through the relay. You can use Tailscale instead.
  • The xAI API cannot run a process near you, so it signs in with OAuth through Public MCP, which Tailscale Funnel publishes from this machine. Grok Bot can use Public MCP too, as an alternative to the connector.
Nothing on overdeck.ai ever sees a tool call in plain text.

Connect in one paste

Pick the bot in Connect a bot, pick its access (by default Read state, Read conversations and Send messages), and click Copy for <bot>. Paste the copied message into the bot’s chat. The bot runs the command inside it, shows you one link, and you click it and Authorize; the bot runs the command again and reports it is ready. The pairing code in the message works once and expires within 30 minutes. If it is refused or expires before the bot finishes, click Copy again (or Copy new once it has expired) under Settings → Anywhere → Bots → “Waiting to connect” and paste the new message. The copied message runs pan mcp connector connect, the one-command path a bot can run again after any result.

Waiting requests

Every copied request appears under Settings → Anywhere → Bots → “Waiting to connect” until the bot pairs, with its expiry: Copy again while the code is still live; Copy new once it has expired or the code was used (burns the old code, issues a new one, and copies its message); Cancel burns the code and removes the request. A dashboard restart drops every waiting request and its code; “Connect a bot” issues a fresh one.

After the bot connects

A paired bot shows a non-blocking Needs-you notice: “<name> connected with <access>” (for example “Read + Tell”), with Revoke (removes the connector at once) and Dismiss (clears the notice; the connector stays paired). The notice disappears on its own 24 hours after the bot connects, when dismissed, or when the connector is removed.

The Connect a bot dialog

Give an outside MCP client (Hermes, OpenClaw, Grok Build, Grok Bot, or a script calling the xAI API) scoped, revocable access to this machine. Open Connect a bot from Settings → Anywhere → Bots, or from the command palette. Only a browser on this machine can connect or manage bots; a paired device sees “Only a browser on this machine can manage bots.” The dialog picks a reach by platform: Access defaults to read:state, read:conversations and tell; read:state is always on. operate and approve are off by default. A bot never gets admin, forward, read:settings, read:costs or read:events, regardless of what is ticked. Each reach produces a different setup:
  • Overdeck connector: a message to paste into the bot, built around a pairing code that works once, within 30 minutes. It runs pan mcp connector connect for you; the manual pairing string and commands (login, pair, serve) live under “Set up by hand instead” in the dialog’s output.
  • Tailscale, This computer: an access token, shown once. The config snippet never carries it: it goes only into the one-time “Token setup” field, kept out of the config through OVERDECK_MCP_TOKEN or OVERDECK_MCP_TOKEN_FILE.
  • Public MCP: the public URL plus, for the xAI API, the pan mcp oauth issue command that mints its token. Public MCP must be on first; while it is off the dialog shows Show Public MCP settings instead.

Platforms

Hermes

The Hermes connector config, for example:
The plugin reads summary and allow_answers from settings; mcp_allowlist grants it the overdeck server. See integrations/hermes/README.md for the /overdeck commands. Connect in one paste registers the connector as a stdio server in mcp_servers instead of this HTTP entry; see integrations/hermes/README.md.

OpenClaw

The OpenClaw plugin lives in integrations/openclaw/. The Overdeck tools come from OpenClaw’s own MCP client, so the server entry needs transport: "streamable-http": OpenClaw defaults to sse, which Overdeck does not serve. The plugin adds a needs-you summary to agent turns, at most every 5 minutes, and two chat tools, overdeck_pending and overdeck_answer. Answering stays off until you set allowAnswers: true, and the connector also needs approve access. OpenClaw 2026.10.10 blocks the summary hook for plugins it does not bundle, so also add hooks: { allowConversationAccess: true } to plugins.entries.overdeck (see the package README). The connector config:
Connect in one paste registers the connector with openclaw mcp set as a stdio server, which gives the agents the Overdeck tools; the plugin’s summary and chat tools still need the HTTP config above.

Grok Build

The Grok Build plugin lives in integrations/grok-build/. Install it with grok plugin install eltmon/overdeck#integrations/grok-build --trust and grok plugin enable overdeck. Its MCP server script runs the paired connector when ~/.overdeck-connector/pairing.json exists, and otherwise pan mcp serve with the token file from “This computer”. Ask /overdeck pending to list prompts that wait for you; on a computer with Overdeck installed, type /overdeck:overdeck pending, because Overdeck’s own overdeck skill has the same name. This plugin makes Grok Build an outside client of Overdeck. It is separate from the grok harness, where Overdeck itself launches Grok Build agents and conversations (see Grok Build CLI). A harness agent already gets its own per-agent overdeck MCP server over ACP, so it does not need this plugin; on a host that runs grok harness agents, the plugin’s own overdeck server also loads into those sessions.

Grok Bot

Pick Grok Bot in Connect a bot and click Copy for Grok Bot; see Connect in one paste. Paste the message into Grok Bot’s chat; it runs pan mcp connector connect itself, shows you a link to click and Authorize, then reports it is ready. Grok Bot can use Public MCP instead: pick the Public MCP reach, then install the Grok Bot plugin and replace its mcp.json, which runs the connector, with your public URL (https://<machine>.<tailnet>.ts.net:8443/mcp). On first use Grok Bot opens an Overdeck sign-in page that shows an approval code. Approve it in your dashboard’s Needs-you card, or run pan mcp oauth approve <code> --level read, and choose the access level there (see Sign in with OAuth).

xAI API

The xAI Responses API calls Overdeck as a remote MCP tool, so it also needs Public MCP. It cannot open a browser, so mint its tokens from the terminal:
Keep the access token in an environment variable and pass it in the authorization field of the mcp tool, with server_url set to the public URL. Runnable TypeScript and Python examples are in integrations/grok-bot/examples/. The access token lasts 30 days; see pan mcp oauth to list and revoke sign-ins.

Run the Overdeck connector

The Overdeck connector runs on the computer where the bot runs. It pairs once with one Overdeck machine and serves that machine’s MCP tools to the bot on http://127.0.0.1:7466/mcp (or stdio). Every tool call travels to the machine over an encrypted secure channel inside a WebRTC connection, so the bot needs no Tailscale and no public address. It needs Node 22.16 or later, and you must sign it in with the overdeck.ai account the machine uses. On a computer without Overdeck, run each command as npx -y @overdeck/core@<version> mcp connector <command>; “Connect a bot” shows the exact version.

The connector home

All connector state lives in $OVERDECK_CONNECTOR_HOME, default ~/.overdeck-connector, mode 0700. It holds up to five files, each mode 0600: account.json (the overdeck.ai sign-in), identity.json (the connector id and its keys), pairing.json (the paired machine and its connector token) and local-token, plus pending-signin.json while a connect sign-in waits for approval. The connector never reads or writes ~/.overdeck, so it can run on an Overdeck machine without touching that machine’s sign-in or keys. A file that other users can read is refused with a chmod 600 hint. login fixes the account and directory URLs for every later command. The directory URL comes from --directory-url, else OVERDECK_CONNECTOR_DIRECTORY_URL, else https://connect.overdeck.ai; the account URL from --account-url, else OVERDECK_ACCOUNT_URL, else https://account.overdeck.ai.

The local endpoint

serve binds 127.0.0.1 only. A bot sends Authorization: Bearer <local token> with every POST /mcp; the token is the content of local-token, and a missing or wrong token gets 401. Keep it out of chat and config files:
/mcp is stateless JSON: each request gets its own MCP session. Bodies over 4 MiB get 413, and GET or DELETE on /mcp get 405. GET /healthz needs no token and answers { "ok": true, "machine": "<label>", "route": "direct" }; route is direct, relay or down, and ok is false when it is down.

Routes and reconnects

The connector tries a direct WebRTC path first. It falls back to the TURN relay only when the account has the relay plan and this month’s relay allowance is not used up; it reports its relay bytes to overdeck.ai. With no direct path and no relay, tool calls fail with No direct path to <machine>. Use the relay plan, or the Tailscale route in the README. After a lost connection it tries again after 1 s, doubling up to 60 s, and at once when overdeck.ai shows the machine online again. A tool call made while the connection is down returns an error; the bot can retry it. Connector errors name each leg (relay: …; direct: …).

What a connector can reach

A connector reaches only the machine it paired with. Its tool list has no list_machines, and start_conversation, start_worker and start_issue have no machine or needs argument: they start work on the paired machine, when the connector holds operate. The machine refuses any other target with 403 connector-local-only. search_conversations returns only the paired machine’s matches, and list_pending_input shows only the paired machine’s input, with a fleetError in place of its linked machines. To reach a second machine, run a second connector with its own OVERDECK_CONNECTOR_HOME.

Re-pairing and logout

Pairing again (for example with new scopes) replaces the connector’s token on the machine and keeps local-token, so the bot’s config keeps working. Restart serve after a re-pair: it reads pairing.json only when it starts. logout does four steps in order: it removes the connector from the machine (DELETE /api/connectors/self), removes it from the overdeck.ai directory, revokes its overdeck.ai sign-in, and deletes its files. A step that fails prints one line and the next step still runs; the files are always deleted. If the machine was unreachable, remove the connector there under Settings → Anywhere → Bots.

Tailscale instead of the connector

If the bot’s computer is already on your tailnet, it can call this machine’s /mcp directly instead of running the connector. Pick Tailscale as the reach in Connect a bot: the dialog creates an access token with the scopes you ticked and shows it once in the “Token setup” field. The bot then calls https://<machine>.<tailnet>.ts.net/mcp with that token as a Bearer header. For a bot in a container, run Tailscale inside the container with an ephemeral, tagged auth key, and give the tag an ACL that reaches only the dashboard host on port 443. The Hermes and OpenClaw READMEs have a “Tailscale route” section with the exact config. Grok Build’s Tailscale route is not working yet (#5029); use the connector or “This computer” for Grok Build.

Troubleshooting

no-webrtc-egress

The connector reached overdeck.ai and got relay credentials, but the computer it runs on got no TURN relay connection, so no WebRTC path can open. The usual cause is an environment that blocks TLS to turn.cloudflare.com:443 and UDP; running the command again then does not help. A relay outage gives the same result, so check that first (next point). What to do: use Public MCP (see Grok Bot above), or run the connector on a host with WebRTC egress, or use Tailscale instead of the connector. How to tell a relay outage from a blocked bot: run pan doctor on the machine. The TURN relay row appears only when the machine is signed in to overdeck.ai with the relay plan. If the row is ok, the block is on the bot’s side; if it warns, the relay or the machine’s own network is the problem. Still stuck? Ask on the Overdeck Discord or file a GitHub Issue.

Remove a bot

Remove in Settings → Anywhere → Bots revokes a connector at once; the connector loses access on its next call. Revoke a Tailscale or “This computer” token in Settings → Access Tokens or with pan token revoke <id>. End a hosted bot’s sign-in in the Sign-ins list or with pan mcp oauth revoke <familyId>. On the bot’s computer, pan mcp connector logout removes the connector and deletes its files.