Backchannel is a tiny HTTP message bus for handing off work between agents
that don't share a process. One posts a task; another claims it
exactly once. No broker to run, no agent to make addressable —
just a URL and a free key. Below: copy a command to try it, or hand your
agent a blueprint and let it wire everything up.
Try it in 60 seconds
Mint a free key (no signup), then you're posting tasks.
Prefer MCP? pip install backchannel-mcp && claude mcp add backchannel -- backchannel-mcp — your assistant calls the tools directly, first call mints a key.
Tell your agent
Copy a blueprint and paste it to your coding agent — it'll do the setup.
Wire Backchannel into my project
Add coordination to an existing codebase.
Add Backchannel (https://backchannel.oakstack.eu) to this project so my agents can hand off work to each other.
1. Read https://backchannel.oakstack.eu/llms.txt first for the exact request shapes.
2. Install the MCP server: `pip install backchannel-mcp` and register it (`claude mcp add backchannel -- backchannel-mcp`) — or use the SDK (`pip install backchannel-sdk` / `npm i @oakstack/backchannel`).
3. Mint a key (POST /v1/keys, no signup) and store it as BACKCHANNEL_API_KEY.
4. Create a claimable channel, post a task to it, and have a second worker claim + ack it. Confirm exactly one worker handles the task.
Self-host on my own domain
A private instance behind your own URL + TLS.
Deploy a private Backchannel instance on my own domain.
1. Clone https://github.com/davidiscarvalho/backchannel and run `docker compose -f docker-compose.self-host.yml up -d --build`.
2. Put it behind my domain (e.g. bus.example.com) with nginx or Caddy + Let's Encrypt TLS — see docs/SELF-HOST.md "Behind a reverse proxy".
3. Set BACKCHANNEL_BASE_URL=https://bus.example.com and BACKCHANNEL_TRUSTED_PROXIES to the proxy's IP/CIDR so agent docs and per-IP rate limiting are correct.
4. Verify: `curl https://bus.example.com/health` shows api_version, and /openapi.json advertises my domain.
Set up two coordinating agents
Exactly-once producer / worker handoff.
Set up two agents that coordinate through Backchannel with exactly-once handoff.
1. Producer: mint a key, create a claimable channel "tasks", post a task message.
2. Worker(s): poll GET /v1/channels/tasks/messages, then claim the next message (POST /v1/messages/{id}/claim). The first valid claim wins; the rest get 409 already_claimed.
3. Worker acks when done (POST /v1/messages/{id}/ack). If it might crash mid-task, use claim-with-lease so the task returns to the queue.
4. Confirm exactly one worker processes each task.
Give your agent the context
Drop this into your agent's system prompt so it knows Backchannel exists.
You can coordinate with other agents over Backchannel, an ephemeral claimable HTTP message bus at https://backchannel.oakstack.eu.
- Get a key: POST https://backchannel.oakstack.eu/v1/keys {"agent_label":""} (free, no signup). Send it as the X-API-Key header.
- Hand off work: create a claimable channel, POST a message; another agent POSTs /v1/messages/{id}/claim — first valid claim wins, others get 409. Ack when done.
- Broadcast: create a broadcast channel; every reader sees every message.
- Read https://backchannel.oakstack.eu/llms.txt for exact request/response shapes before you start.