> ## Documentation Index
> Fetch the complete documentation index at: https://panopticon-cli.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect a bot: give Hermes, OpenClaw or Grok scoped MCP access

> Give a chat bot or a hosted assistant scoped, revocable access to Overdeck through the Overdeck connector, Tailscale or public MCP

# 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](https://panopticon-cli.com/configuration/mcp.md) 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](https://panopticon-cli.com/configuration/mcp.md#public-mcp-for-hosted-bots), 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`](https://panopticon-cli.com/cli/mcp#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:

| Platform | Reaches |
| - | - |
| Hermes, OpenClaw | Overdeck connector (default), Tailscale |
| Grok Build | This computer (default), Overdeck connector, Tailscale |
| Grok Bot | Overdeck connector (default), Public MCP |
| xAI API | Public MCP |

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:

```yaml theme={null}
# ~/.hermes/config.yaml: connector route (default)
mcp_servers:
  overdeck:
    url: "http://127.0.0.1:7466/mcp"
    headers:
      Authorization: "Bearer ${OVERDECK_CONNECTOR_LOCAL_TOKEN}"
plugins:
  enabled: [overdeck]
  entries:
    overdeck:
      mcp_allowlist: ["overdeck"]
      settings:
        summary: true
        allow_answers: false
```

The plugin reads `summary` and `allow_answers` from `settings`; `mcp_allowlist`
grants it the `overdeck` server. See
[`integrations/hermes/README.md`](https://github.com/eltmon/overdeck/tree/main/integrations/hermes)
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`](https://github.com/eltmon/overdeck/tree/main/integrations/hermes).

### OpenClaw

The OpenClaw plugin lives in [`integrations/openclaw/`](https://github.com/eltmon/overdeck/tree/main/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:

```json5 theme={null}
// openclaw config
mcp: { servers: { overdeck: {
  url: "http://127.0.0.1:7466/mcp",
  transport: "streamable-http",   // the default is "sse", which Overdeck does not serve
  headers: { Authorization: "Bearer ${OVERDECK_CONNECTOR_LOCAL_TOKEN}" },
} } },
plugins: { entries: { overdeck: { config: { localToken: "${OVERDECK_CONNECTOR_LOCAL_TOKEN}" } } } },
```

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/`](https://github.com/eltmon/overdeck/tree/main/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](https://panopticon-cli.com/configuration/harnesses.md#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](#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](https://panopticon-cli.com/configuration/mcp.md#public-mcp-for-hosted-bots)
instead: pick the Public MCP reach, then install the
[Grok Bot plugin](https://github.com/eltmon/overdeck/tree/main/integrations/grok-bot)
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](https://panopticon-cli.com/configuration/mcp.md#sign-in-with-oauth)).

### xAI API

The xAI Responses API calls Overdeck as a remote MCP tool, so it also needs
[Public MCP](https://panopticon-cli.com/configuration/mcp.md#public-mcp-for-hosted-bots). It cannot open a
browser, so mint its tokens from the terminal:

```bash theme={null}
pan mcp oauth issue --name xai-api --level read
```

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/`](https://github.com/eltmon/overdeck/tree/main/integrations/grok-bot/examples).
The access token lasts 30 days; see [`pan mcp oauth`](https://panopticon-cli.com/cli/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.

| Command | What it does |
| - | - |
| `pan mcp connector connect '<pairing string>' [--name <bot>] [--platform <id>] [--wait <seconds>] [--account-url <url>] [--directory-url <url>]` | Signs in, pairs, verifies and prints the MCP registration in one command a bot can run again; the message from Connect a bot runs it. `--platform` is `grok-bot`, `grok-build`, `hermes`, `openclaw` or `other` (default). See [`pan mcp connector connect`](https://panopticon-cli.com/cli/mcp#connect). |
| `pan mcp connector login [--account-url <url>] [--directory-url <url>]` | Signs the connector in to overdeck.ai with the device flow: open the URL it prints and enter the code. |
| `pan mcp connector pair '<pairing string>' [--label <name>]` | Pairs with the machine named in the string from "Connect a bot". `--label` names the connector on the machine (default: the host name). |
| `pan mcp connector serve [--port <port>] [--stdio] [--label <name>]` | Serves the tools on `127.0.0.1:<port>` (default 7466) until stopped, or one stdio session with `--stdio`. |
| `pan mcp connector status [--port <port>]` | Prints the account, the paired machine, its scopes and the live route of a running `serve`. It never prints a token. |
| `pan mcp connector logout` | Removes the connector from the machine and overdeck.ai, then deletes its files. |

### 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:

```bash theme={null}
export OVERDECK_CONNECTOR_LOCAL_TOKEN="$(cat "${OVERDECK_CONNECTOR_HOME:-$HOME/.overdeck-connector}/local-token")"
curl -s http://127.0.0.1:7466/mcp \
  -H "Authorization: Bearer $OVERDECK_CONNECTOR_LOCAL_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

`/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](https://github.com/eltmon/overdeck/issues/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](https://panopticon-cli.com/configuration/mcp.md#public-mcp-for-hosted-bots)
(see Grok Bot above), or run the connector on a host with WebRTC egress, or
use [Tailscale instead of the connector](#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](https://discord.gg/ZpHE2ZTv5P) or file a
[GitHub Issue](https://github.com/eltmon/overdeck/issues).

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.