Chat bridge

The bridge is a small daemon that:

  1. Listens on a Unix socket at the configured transport’s socket_path.
  2. Forwards messages from ctrlrelay to a chat channel.
  3. Streams replies back from that channel and delivers them to the socket client that asked.

It speaks Telegram or Mattermost. Pipelines never know which: they talk to the socket, and the chat app is the bridge’s business. Switching is a one-line config change and no pipeline code moves.

One at a time. transport.type names the transport that is active, and the other block is inert — it may stay in the file, but nothing reads it, including its question_ttl_seconds. There is no fallback: a question goes to the one you named or nowhere. Running both at once is not supported and not planned — it was designed in #176 and closed won’t-do. Reopen that issue rather than re-deriving the design if you need it.

  Telegram Mattermost
Needs a bot from BotFather, your chat id a self-hosted server, a bot account, a channel id
Outbound Bot API sendMessage POST /api/v4/posts
Inbound getUpdates long-poll WebSocket posted events
“answer this one” the reply gesture reply in the question’s thread
Tappable choices reply keyboard rendered as a numbered list you type

The one operator-facing difference worth knowing. When several questions are outstanding, the bridge can only route your answer if it knows which question you mean. On Telegram that is Telegram’s reply; on Mattermost it is replying inside the question’s thread. A loose message in the channel is only routable when exactly one question is waiting — otherwise the bridge refuses and tells you what is outstanding, rather than guessing.

Pipelines use it as the human-in-the-loop channel: when the agent (Claude Code or OpenCode) writes a BLOCKED_NEEDS_INPUT checkpoint, the pipeline calls transport.ask(question), which travels socket → bridge → chat → you → chat → bridge → socket and returns as a string back into the resume call.

The bridge is implemented in src/ctrlrelay/bridge/.

Prerequisites

Pick one transport and follow its setup section; both end at Start the bridge.

  Telegram Mattermost
Account a Telegram account a self-hosted Mattermost server, with System Console access to enable bot accounts
Bot a bot registered with BotFather a bot account and its token
Destination your numeric chat ID the 26-character ID of a channel the bot is a member of

Either way, the bridge socket directory must exist and be writable. Default is ~/.ctrlrelay/.

Telegram setup

1. Create a bot via BotFather

  1. Open Telegram and message @BotFather.
  2. Send /newbot.
  3. Choose a display name (e.g. ctrlrelay orchestrator).
  4. Choose a unique username ending in bot (e.g. myorg_devsync_bot).
  5. BotFather replies with an HTTP API token that looks like 123456:ABCdef-.... Save this — it’s your bot token.

2. Get your chat ID

  1. Open the chat with your new bot and send any message (e.g. hello). Telegram won’t deliver bot messages until the chat exists.
  2. Hit the getUpdates endpoint with your token:

    curl "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates" | jq
    
  3. Find the numeric message.chat.id field. That’s your chat ID. For private chats it’s a positive integer; for groups it’s negative.

If you’d rather use a Telegram group, add the bot to the group and use the group’s chat ID instead.

3. Configure ctrlrelay

Set the bot token in your environment (the bridge reads it from the env var named in transport.telegram.bot_token_env):

export CTRLRELAY_TELEGRAM_TOKEN="123456:ABCdef-your-real-token"

Update config/orchestrator.yaml:

transport:
  type: "telegram"
  telegram:
    bot_token_env: "CTRLRELAY_TELEGRAM_TOKEN"
    chat_id: 987654321              # your numeric chat ID
    socket_path: "~/.ctrlrelay/ctrlrelay.sock"

Validate:

ctrlrelay config validate

Then go to Start the bridge.

Mattermost setup

1. Enable bot accounts

System Console → Integrations → Bot Accounts → Enable Bot Account Creation = true.

On a self-hosted install this is off by default. Note that editing config.json on the server may not be enough — if the instance has no config watcher the value will not take effect until systemctl restart mattermost, and the live value is what matters. Read it back before believing it:

curl -s "https://<your-server>/api/v4/config/client?format=old" \
  | jq .EnableBotAccountCreation

EnableUserAccessTokens is not required. That setting governs user personal access tokens; bot account tokens are managed separately. Leaving it off avoids letting every user mint long-lived full-access tokens.

2. Create the bot and its token

  1. Integrations → Bot Accounts → Add Bot Account.
  2. Username ctrlrelay, role Member. Leave post:all and post:channels off — the bot will be added to one channel, and a token with no reach beyond it is a smaller problem if it leaks.
  3. Create New Token and copy it immediately. Mattermost shows it once.

3. A channel, and put the bot in it

Create a channel for orchestrator questions, then invite the bot:

/invite @ctrlrelay

This is not optional, and the reason is easy to miss. A bot without post:all cannot post where it is not a member — and it does not receive the reply events for such a channel either. Forget this and questions fail to post and answers would never arrive. ctrlrelay bridge start checks membership before it binds its socket and refuses to start until the bot is invited.

The bot must also be on the team. If /invite complains, add it via the team’s Invite People first.

4. Find the channel id

The id, not the name: a name is only unique within a team and can be renamed under you, while the id is stable. From the channel’s View Info, or:

curl -s -H "Authorization: Bearer $CTRLRELAY_MATTERMOST_TOKEN" \
  "https://<your-server>/api/v4/teams/name/<team>/channels/name/<channel>" \
  | jq -r .id

5. Configure

export CTRLRELAY_MATTERMOST_TOKEN="your-bot-token"
transport:
  type: "mattermost"
  mattermost:
    url: "https://chat.example.com"   # scheme required
    bot_token_env: "CTRLRELAY_MATTERMOST_TOKEN"
    channel_id: "emzhur1hwpyc38ehkfm5ppym8y"
    socket_path: "~/.ctrlrelay/ctrlrelay.sock"
    ask_timeout_seconds: 900

Validate:

ctrlrelay config validate

Editions. Everything here works on free self-hosted Mattermost. The REST API, the WebSocket, bot accounts and bot tokens are core features, not licensed ones; the paid tiers cover SSO/SAML/LDAP, compliance export and high availability, none of which the bridge touches.

Start the bridge

ctrlrelay bridge start is the same command for either transport; it reads transport.type and starts that one.

Foreground (handy when wiring up for the first time — Ctrl+C to stop; also what launchd/systemd units use):

ctrlrelay bridge start --foreground

Background — the default: forks, writes a PID file alongside the socket and returns to the shell:

ctrlrelay bridge start

Check it’s alive:

ctrlrelay bridge status

Stop it:

ctrlrelay bridge stop

Send a test message

Once the bridge is running and reachable on its socket, send a one-off message through it:

ctrlrelay bridge test --message "hello from ctrlrelay"

You should see the message appear in your Telegram chat or Mattermost channel almost immediately. If you don’t, see Troubleshooting.

How it integrates with pipelines

When you run ctrlrelay poller start (or run dev) with transport.type set to telegram or mattermost, the pipeline auto-connects to the bridge socket if it exists. Messages it sends:

  • 🔔 New issue #123 in your-org/your-app: ... — when the poller picks up an issue.
  • ⏸️ Blocked on #123: ... — the agent wrote a BLOCKED_NEEDS_INPUT checkpoint; reply to that message (Telegram) or in its thread (Mattermost) to answer it.
  • ✅ PR ready: ... — pipeline finished green.
  • ❌ Failed on #123: ... — pipeline failed.

A question asked again is marked. A scheduled sweep starts a fresh session each day and the agent often reaches the same blocker and asks again, in new words. When that happens the post carries a line such as Repeat: asked 3 times before, last on Oct 28 UTC, no answer yet. Two questions count as the same if they cite at least one PR or issue number in common (or, when neither cites a number, have the same text). The count runs from the last answer to that question, including an answer on a row a later re-block rewrote (rows rewritten before this was kept can still count too high). The history this reads is kept for question_retention_days.

A question nobody answers is asked less often. On the scheduled secops sweep, each earlier post of the same question that got no answer counts as a miss: one that expired on question_ttl_seconds, or one still open and more than 6 hours old (one closed as resolved elsewhere does not count, and neither does one that never reached the chat because the bridge was down, the post failed, or the bridge never confirmed it). After one miss the next post waits 1 day from the last post, after two 2 days, after three 4 days, then once a week, so a daily sweep posts it on days 0, 1, 3, 7, 14, 21. An answer to any post of it resets the count. A held question is not posted and gets no blocked on <repo> message; the sweep summary lists it with its session id and the time it is next due, and the poller logs secops.question.held. The session still ends blocked with its row saved, so it stays answerable and expires on the TTL like any unanswered question. To answer it, name its session in a message, or reply to the earlier post: while that post’s own session is still open the reply answers that session; once it has expired without an answer, the reply goes to the newest open session asking the same thing in that repo, and the confirmation says so. A manual ctrlrelay run secops never holds a question back.

For the full BLOCKED → answer → resume mechanics, see Feedback loop.

Protocol

The bridge speaks newline-delimited JSON over the Unix socket. Defined in src/ctrlrelay/bridge/protocol.py.

op Direction Purpose
send client → bridge Fire-and-forget message into the chat.
ask client → bridge Question that expects a reply. Optional options[] renders as a Telegram reply keyboard, or a numbered list on Mattermost.
ack bridge → client Acknowledges receipt of send/ask.
answer bridge → client Reply text from the operator, returned to the original ask caller.
ping / pong both Liveness check.
error bridge → client Error envelope (error and message fields).

You generally don’t need to speak the protocol directly — use ctrlrelay.transports.SocketTransport from Python or the bridge CLI commands.

Troubleshooting

“Bridge not running” when calling bridge test — start the bridge first with ctrlrelay bridge start. Confirm with bridge status.

Nothing arrives in Telegram — check the bot token: curl https://api.telegram.org/bot<TOKEN>/getMe should return your bot. If it returns 401, the token is wrong or the bot was deleted.

Nothing arrives in Mattermost — ctrlrelay bridge start checks the token and the bot’s channel membership before it binds the socket, and says which failed. Check url has its scheme (https://), channel_id is the 26-character id rather than the name, and the bot was invited to the channel.

Replies don’t reach the pipeline — make sure you’re replying in the configured chat (chat_id) or channel (channel_id). With more than one question outstanding, answer by replying to the question — Telegram’s reply gesture (long-press → Reply) or a reply in the Mattermost thread. A loose message is refused when the bridge cannot tell which question it answers.

Bridge already running (PID n) on start — the PID file names a live process. Stop it with ctrlrelay bridge stop first. A PID file left by a run that died is removed automatically on the next start.

Rate limits (Telegram) — Telegram caps individual chats at ~20 messages/minute. The bridge does not implement client-side rate limiting; if you saturate the chat you’ll see HTTP 429 in the bridge logs and the affected send/ask calls will fail. Slow your pipelines down or split notifications across chats.

Bridge crashes when network is offline — the bridge requires access to the chat server. If the network is down at startup, the Telegram long-poll fails, or the Mattermost WebSocket does not authenticate within 30 seconds, and the process exits. Restart the bridge once connectivity is restored. (When run under launchd / systemd with KeepAlive/Restart=always, this is automatic.) Once running, the Mattermost handler reconnects its WebSocket with backoff.

Socket exists but no process — if bridge status reports “socket exists but no running process”, remove the orphan socket file (rm ~/.ctrlrelay/ctrlrelay.sock) and restart.

Sequence: BLOCKED question round-trip

sequenceDiagram
    participant P as Pipeline
    participant B as Bridge
    participant C as Chat (Telegram or Mattermost)
    participant U as Operator
    P->>B: ask("Which?")
    B->>C: post question
    C->>U: notification
    U->>C: reply
    C-->>B: reply + id of the post it answers
    B-->>P: answer("the b")

The bridge remembers the id of every question it posts, so the reply’s “this is what I am answering” — Telegram’s reply_to_message_id, Mattermost’s thread root_id — names the session exactly. That is also how an answer arriving after the pipeline stopped waiting still drives a resume, via the pending_resumes table.

The pipeline’s transport.ask() call blocks (up to ask_timeout_seconds) until the bridge returns the answer. The pipeline then resumes the agent session — claude --resume <id> or opencode run --session <id> — with a prompt of the form “User answered: …”.