bud-relay

Ask your ChatGPT dot something from Claude Code: it wakes on its own and answers in about 20 seconds.

bud-relay is one self-hosted MCP server where your AI agents from different vendors send each other requests and replies: OpenAI's dot, Claude Code on your computer or in the cloud, Claude Duet and Meta Muse. Every agent has a mailbox, and the relay wakes the ones it can. Every message is marked untrusted.

• For people who use more than one of these agents and want them to ask each other things, and who can run a small server.

• Duet cannot be woken. It reads its mail only when you chat with it.

• You need uv, a machine that stays on, a public HTTPS URL (Tailscale Funnel or a Cloudflare Tunnel), and the agents you want to connect.

 Duet       Claude Code cloud      dot              Muse               Claude Code (Mac)
   │          │         ▲            │   ▲            │   ▲               │   ▲
   │          │         │ routine    │   │ MCP        │   ┆ Muse          │   │ channel
   │          │         │ trigger    │   │ Events     │   ┆ bridge        │   │ (optional)
   │          │         │            │   │            │   ┆ (unofficial)  │   │
   ▼          ▼         │            ▼   │            ▼   ┆               ▼   │
 ┌─────────────────────────────────────────────────────────────────────────────────────────┐
 │ bud-relay: a mailbox per agent, wake-ups, deadlines, retries, a shared board            │
 └─────────────────────────────────────────────────────────────────────────────────────────┘
   ▼ every agent calls the same MCP tools        ▲ the relay wakes an agent where it can

Agents, and what is tested

Duet has no official wake-up, so send urgent Claude work to Claude Code: on your computer, or a cloud routine (not yet tested live). bud-relay never automates claude.ai. Push uses standards where they exist: MCP Events, which OpenAI ships for dots, and Claude Code's routines and channels. Each vendor's quirks live in one module under src/bud_relay/agents/, so an official wake-up added later changes that module, not the core.

Related MCP server: NornWeave

Connect in three steps

1. Run the relay on a machine that stays on, and give it a public HTTPS URL:

   uv tool install bud-relay    # or prefix each command with uvx
   mkdir my-relay && cd my-relay
   bud-relay init               # relay.toml and .env with a fresh owner key; never overwrites
   tailscale funnel --bg 8787   # prints https://<machine>.<tailnet>.ts.net

   Set public_url in relay.toml to that origin (no path): ChatGPT and claude.ai cannot reach the default 127.0.0.1. Delete the agents you do not use. If you delete duet but keep claude-cloud, also delete its via = "duet" line. Then run bud-relay serve (http://127.0.0.1:8787) and leave it running. Behind Cloudflare, see SETUP.md first.

2. Run connect for an agent:

   bud-relay connect dot    # likewise: duet, claude-cloud, claude-code, muse

   It prints a one-time pairing code (or, for an agent with an API key, puts a new key on your clipboard) and that agent's steps with your URLs filled in.

3. Paste and type. For the dot: at chatgpt.com/plugins choose + > Add custom MCP server, paste the URL, choose OAuth and Create as a plugin, press the plugin's Connect button and type the pairing code. Then paste the subscribe prompt that connect dot prints into a chat with the dot. Without it, the relay cannot wake the dot. For claude.ai, add a custom connector with client id bud-relay. For Claude Code or Muse, paste the command or prompt the steps give.

To try it first with stand-in agents and no tunnel, clone the repo and run uv run bud-relay demo --no-claude (SETUP.md). SETUP.md also covers connecting from another machine with --relay, Docker, and the tests.

How a message flows

1. An agent calls send(to, text). The relay puts the request in the recipient's mailbox and answers at once with its message_id and thread_id.

2. If the recipient has a waker, the relay uses it. A waker that cannot be retried, or still fails after 5 tries, does not lose the request: it stays in the mailbox, and the sender gets a note.

3. The recipient reads the request inside an envelope that names the sender and says the text comes from another agent, not from its owner. It answers with reply, and may add report_progress lines while it works. Until then the request stays in its inbox, so every chat or session that checks sees it, and every tool result's unanswered counts it.

4. The reply lands in the sender's mailbox. The first reply wins; a later one is refused.

5. A request with no reply by its deadline (reply_timeout_hours, 12 in the config init writes) expires, and the sender gets an error.

Agents can also share notes on a small versioned board (board_put, board_get, board_list).

Limits

• Duet cannot be woken. It reads its mail when you chat with it, or when a routine you asked it to set up runs.

• The relay must stay up, on a machine that does not sleep, at a public URL that does not change.

• Claude Code cloud fires a routine at most 30 times an hour, and each request starts a new session on your plan.

• Messages are stored as plain text in SQLite on the relay's machine, and nothing is deleted automatically.

• The untrusted envelope is a label, not a sandbox. Each agent's own approval rules are what stop it from acting on a bad request.

• Not yet tested live: the dot's subscription renewal past one day, Duet's routine answering a request, claude.ai registering itself (empty client fields), Claude Code cloud, the Claude Code channel, and Muse reading its inbox through its connector.

FAQ

Does it work in the ChatGPT desktop app? No. Connect the dot at chatgpt.com/plugins in a web browser. The desktop app's MCP settings set up Codex, not your dot.

Do I upload a plugin .zip? No. Add a custom MCP server, create it as a plugin, then press the plugin's Connect button.

Why didn't Duet answer? Duet cannot be woken. It reads its mail when you chat with it ("Check my mail"), or when a routine you asked it to set up runs. Send urgent Claude work to Claude Code.

Muse gets error 1010 or a 403. Cloudflare's Browser Integrity Check blocks it before the relay sees it. Turn it off for the relay's hostname (SETUP.md).

Is it official? No. bud-relay is not affiliated with Anthropic, OpenAI or Meta.

What does it cost? bud-relay is free (MIT) and runs on your machine. Each agent runs on its vendor's plan, and each Claude Code cloud wake-up starts a session on yours.

Which plans do I need? One that gives you each agent you connect: a Claude plan with Duet, or with Claude Code on the web for the cloud agent; a ChatGPT account with a dot; Meta Muse. bud-relay itself needs no account.

Security in short

• Relayed text is untrusted. The relay wraps everything it hands an agent in an envelope that names the sender and says the text is information to weigh, not its owner's instructions. Each agent keeps its own approval rules; the envelope is a label, not a sandbox.

• Every agent signs in as itself, with its own API key or an OAuth connection you approve with a pairing code that works once, for 10 minutes.

• The owner key is for the admin only. It makes pairing codes and keys; never give it to an agent.

• Self-registering clients are fenced in. claude.ai and ChatGPT may register themselves, but only with redirects to the hosts in allowed_redirect_hosts (claude.ai, chatgpt.com).

• Webhooks are signed, and the relay listens on loopback: expose it only through an HTTPS tunnel.

Details, and how to report a problem: SECURITY.md.

Related work and credits

Mailboxes for coding agents already exist (MCP Agent Mail), and so do single bridges such as dots-bridge. bud-relay's point is one self-hosted server for the always-on agents of several vendors, with deadlines, retries, untrusted marking and a shared board.

The OAuth provider and the MCP Events code are ported from dots-bridge (MIT, Copyright (c) uezo). Each ported module says so in its header.

License

MIT. Ported dots-bridge code keeps its own MIT notice in THIRD_PARTY_NOTICES.md.

Development

SETUP.md runs the tests and the end-to-end demo. CONTRACT.md describes how the parts fit together: the data model, the tools, auth, and the agent types.