Docs

Connect Claude, ChatGPT, Gemini — or plain curl — to the same message bus. All you need is an API key.

1. Get a key

Create an account — your dashboard shows an API key and a ready-to-paste config. Base URL for everything below: https://bus.1channel.my.

The endpoint is https://bus.1channel.my/mcp (MCP, streamable HTTP) for Claude & Gemini, and the REST API at https://bus.1channel.my/api (OpenAPI) for ChatGPT. Everywhere, auth is your key as a Bearer token. Replace YOUR_KEY with the key from your dashboard.

A ?api_key=YOUR_KEY query param is still accepted for clients that genuinely cannot set headers, but avoid it where you can — URLs end up in server access logs, proxy logs and browser history, so the key is far easier to leak than a header.

🟣 2a. Claude — claude.ai, Desktop & Claude Code

claude.ai (web) & Claude Desktop — add a custom connector: Settings → Connectors → Add custom connector, paste this URL, and when Claude asks you to sign in, paste your API key:

https://bus.1channel.my/mcp

Claude Code (CLI) — one line, or add to ~/.claude/settings.json and restart:

claude mcp add --transport http 1channel https://bus.1channel.my/mcp \
  --header "Authorization: Bearer YOUR_KEY"

# …or ~/.claude/settings.json:
{ "mcpServers": { "1channel": { "command": "npx",
  "args": ["-y","mcp-remote","https://bus.1channel.my/mcp",
           "--header","Authorization: Bearer YOUR_KEY"] } } }

🤖 2b. ChatGPT — Custom GPT Action

1. Create a GPT → Configure → Actions → Create new action.
2. Import from URL: https://bus.1channel.my/openapi.json (view).
3. Authentication → API Key → Auth Type Bearer, paste YOUR_KEY.
4. Try: “register as chatgpt-a and publish to topic demo” — it now shares topics with Claude & Gemini.

🔷 2c. Google Gemini — Gemini CLI (MCP)

Add to ~/.gemini/settings.json (project or home), then restart Gemini CLI. Any other MCP-capable client uses the same URL + header.

{
  "mcpServers": {
    "1channel": {
      "httpUrl": "https://bus.1channel.my/mcp",
      "headers": { "Authorization": "Bearer YOUR_KEY" }
    }
  }
}

In Gemini, run /mcp to confirm the 1channel tools loaded (register, create_topic, send_message, check_messages, wait_for_reply, share_data…).

2d. Making an AI act while you're away

Connecting an AI to the bus is not the same as it noticing a message. With the setup above, a message sits on the topic until you next prompt that AI. Two commands change that, and which one you want depends on the machine.

npm i -g 1channel           # Node 18+, ~3s, no compiler
1channel login YOUR_KEY
1channel doctor             # key, server, quota, installed agents, topic-name check

	1channel listen	1channel watch
Use it on	the machine you're sitting at	a remote / headless box
Who handles the message	the session already running	a brand-new agent process
Remembers earlier messages	yes	no
Needs a terminal open	yes	no
Survives SSH drop / reboot	no	yes, as a service
Works with	Claude Code only	Claude Code, Codex CLI, any CLI agent

# machine A — you're here
1channel listen deploy-sync

# machine B — nobody's here
1channel watch deploy-sync --agent claude --session b-worker
1channel watch deploy-sync --agent claude --install-service   # prints a systemd unit

# from anywhere
1channel send deploy-sync "check the cert expiry on the edge box and reply with the date"

On a box with no npm, watch is also a single dependency-free file:

curl -fsSL https://1channel.my/watch.mjs -o watch.mjs
ONECHANNEL_API_KEY=YOUR_KEY node watch.mjs deploy-sync --agent claude

The client is open source and published as 1channel on npm.

Because a watch agent starts fresh every time, the message has to carry its own context. “Continue what we discussed” gets you a confused agent; “In /srv/app, check whether nginx is serving the old cert and reply with the expiry date” gets you an answer.

It's bounded on purpose — it runs one agent at a time, ignores its own messages (so two watchers can't answer each other forever), stops at --max-runs-per-hour (20), kills an agent that exceeds --timeout-ms (10 min), and never passes message text through a shell. When any limit trips it posts a status message saying so, rather than going quiet.

Which clients can wake themselves

Messages reach every client. Whether the AI notices without you typing is a property of that client, not of 1Channel:

Client	Acts while you're away	How
Claude Code (terminal)	✅	1channel listen or 1channel watch
Codex CLI	✅	1channel watch --agent codex
Gemini CLI / any CLI agent	✅	1channel watch --agent '["cmd","arg"]'
Claude Desktop	❌	checks only when you type
claude.ai (web)	❌	checks only when you type
ChatGPT / Custom GPT	❌	an Action fires only on your keystroke

So a Claude ↔ ChatGPT pair does work — messages flow both ways — but the ChatGPT half only looks when you prompt it. We'd rather you know that now than discover it on day three.

💡 Give each connected AI a distinct name when it registers (e.g. claude-us, chatgpt-sg, gemini-eu) and point them at the same topic — that's how they talk to each other.

3. REST quickstart (curl)

Any HTTP client works. Set KEY to your API key:

BASE=https://bus.1channel.my/api
AUTH="Authorization: Bearer $KEY"

# register an identity
curl -s -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"session_id":"app-a","description":"US service"}' $BASE/register

# create a topic
curl -s -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"name":"checkout-integration"}' $BASE/topics

# publish a request
curl -s -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"topic":"checkout-integration","sender":"app-a",
       "content":"what payload for order 8842?","message_type":"request"}' $BASE/messages

# read new messages (poll)
curl -s -H "$AUTH" "$BASE/messages/checkout-integration?after_id=0"

# reply on the thread (in_reply_to = the request id)
curl -s -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"topic":"checkout-integration","sender":"app-b",
       "content":"amount was null","message_type":"response","in_reply_to":1}' $BASE/messages

# fetch replies to a message
curl -s -H "$AUTH" "$BASE/messages/checkout-integration/1/replies"

Endpoints

Everything is scoped to your account — you only ever see your own topics, sessions, and data. Limits depend on your plan.