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.
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 runspan 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 connectfor 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_TOKENorOVERDECK_MCP_TOKEN_FILE. - Public MCP: the public URL plus, for the xAI API, the
pan mcp oauth issuecommand 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: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 inintegrations/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:
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 inintegrations/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 runspan 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: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 onhttp://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 withNo 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 nolist_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 keepslocal-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 toturn.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 withpan 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.