chaos-relay

name

chaos-relay

description

Drive the pi agent from, and reply to, Telegram, Discord, email, and webhooks via a CHAOS relay server. Use when the user wants to set up the relay bridge, connect a channel (Telegram bot, Discord bot, email, webhook), check for inbound messages from those channels, reply to a thread the agent received, or describe any "I want to message my agent / control pi from chat / email" need. This is the bridge between external channels and the pi agent.

CHAOS Relay Bridge

This skill connects pi to a CHAOS relay server so messages from Telegram, Discord, email, and webhooks reach the agent, and the agent can reply back to those threads. It is how pi gets a two-way inbox outside the terminal.

How it works

External channels deliver messages to the relay. The extension maintains a WebSocket connection (with a safety poll backstop) and surfaces new messages automatically while a pi session is active. The agent answers with the relay_reply tool (add files: [absolute paths] to attach images or files — Telegram shows images inline, email gets real attachments; max 3 files, 5MB each). You can also pull on demand with relay_check_messages.

Credentials live in ~/.pi/chaos-relay.json (0600). Identity is an ECDSA P-256 keypair generated at first setup — the relay binds the session to it, and every authenticated request is signed. The API key is auto-derived from the keypair.

First-time setup (zero-config)

The default path needs no jargon and no Googling:

1. The user gives you one thing — a Telegram bot token, a Discord bot token, an email address, or the word "webhook".
2. Run /chaos-relay connect <that thing> (or call the relay_connect tool). It auto-detects the channel type from the value's shape, self-provisions a relay session (generates the keypair, registers with the relay, persists credentials) if none exists yet, then registers the channel.
3. Return the per-channel finishing step to the user (see below).

Only fall back to the interactive /chaos-relay setup wizard if the user wants to choose a specific relay URL or agent id. That path is also what --advanced exposes. Env vars (CHAOS_RELAY_URL, CHAOS_RELAY_API_KEY) still override everything for headless/explicit setups.

Connecting each channel type

Telegram (most common):

1. User creates a bot via @BotFather and copies the token.
2. /chaos-relay connect <token> (or relay_register_telegram).
3. Returns channelId, botUsername, and a pairingCode.
4. Finishing step for the user: open Telegram, message the bot, and send the pairing code to link the chat. After that, text, photos, and files sent to the bot arrive as inbound messages.

Discord:

1. User creates a bot in the Discord Developer Portal (Bot → Token).
2. /chaos-relay connect <token> (or relay_register_discord).
3. Returns channelId, botUsername, and a pairingCode.
4. Finishing step for the user: send the pairing code to the bot in Discord. Note: Discord has no setWebhook, so the bot's interaction endpoint (or a gateway relay) must be pointed at the relay's /discord/<channelId> URL.

Email:

1. /chaos-relay connect <[e-mail]> (or relay_register_email). (Relay must have CHAOS_EMAIL_DOMAIN configured.)
2. Returns channelId and an inboundAddress.
3. Finishing step for the user: click the verification link sent to their address. Once verified, mail text and attachments sent to the inbound address reach the agent.

Webhook (inbound only — no reply):

1. /chaos-relay connect webhook or connect webhook <name> (or relay_register_webhook).
2. Returns a public webhookUrl. Any external service that POSTs JSON, form data, or plain text to it delivers a message to the agent. There is no reply path for webhooks — do not call relay_reply for them.

If connect can't tell what the user pasted, it asks them to prefix the type explicitly: telegram <token>, discord <token>, email <addr>, webhook <name>.

Receiving and replying

• New messages are injected automatically (WebSocket push, with a safety-poll backstop). Telegram/email attachments are downloaded through the signed relay, saved to private local paths shown in the message, and supported images are also supplied directly as image context. To pull immediately, call relay_check_messages.
• Attachment limits are 3 files per message and 5MB each. A failed/expired file is reported without losing the accompanying text. Do not claim an attachment was received unless its local path or image content appears in the message.
• To answer, call relay_reply with the channelType, channelId, and the inbound message id (as replyTo), plus your content.
• Replies go back to the original channel thread.

Tools

Tool	Purpose
relay_connect	One-shot: paste a token/email and it self-provisions + registers
relay_register_telegram	Register a Telegram bot channel (explicit)
relay_register_discord	Register a Discord bot channel (explicit)
relay_register_email	Register an email channel (explicit)
relay_register_webhook	Create an inbound-only webhook URL
relay_check_messages	Poll for new inbound messages and materialize attachments
relay_reply	Reply to a channel message
relay_list_profiles	List connection profiles and the active one
relay_switch_profile	Switch to (or create) a connection profile

Commands

Command	Purpose
/chaos-relay connect <value>	Zero-config: one paste provisions + registers
/chaos-relay setup [--advanced]	Interactive credential setup (self-provisions by default)
/chaos-relay add	Guided wizard to add a channel
/chaos-relay profile [name]	List connection profiles, or switch to / create one
/chaos-relay status	Config, poller state, live relay health
/chaos-relay poll	Poll once now and deliver any new messages
/chaos-relay stop	Stop the background poller
/chaos-relay approvals <off|writes|all>	Set/show the tool-approval policy

For diagnosis and recovery, see the companion chaos-relay-troubleshoot skill (/chaos-relay doctor, /chaos-relay reset).

Multiple connections (profiles)

Each profile is a separate identity (its own keypair → message queue), so a user can run more than one connection. The profile is bound to the pi session and persists across restarts (resuming a session reconnects as the same identity).

• "switch to my work connection" / "make a new profile called staging" → relay_switch_profile (creates + auto-provisions if new), or /chaos-relay profile <name>.
• "what connections do I have" → relay_list_profiles or /chaos-relay profile.
• Switching changes the one connection this pi instance uses. To run two connections at once, the user launches separate pi instances with CHAOS_RELAY_PROFILE=<name>. Each instance needs its own channel (e.g. a different Telegram bot) to be addressable.

Tool approvals

When the agent acts on an inbound channel message, you can gate destructive tools: off = fully autonomous (default), writes = ask over the channel before shell/edit/write, all = ask before every tool. Set with /chaos-relay approvals writes or the CHAOS_RELAY_APPROVAL_MODE env var.