Channels Overview

The gateway

flowly gateway starts a single local daemon built on three pieces:

• Gateway server — an aiohttp HTTP + WebSocket app bound to 127.0.0.1:18790. It serves /health, cron/provider HTTP routes, artifact routes, and a /ws WebSocket for the desktop/TUI clients. This is the direct-client surface; it is not the channel transport. Channels run independently.
• Message bus — two asyncio queues (inbound, outbound) that decouple channels from the agent. Channels publish inbound messages; the agent consumes them and publishes outbound responses; a dispatcher routes outbound replies back to the originating channel.
• ChannelManager — instantiates the enabled channels from config, starts them all (plus the outbound dispatcher), and routes each outbound message to the matching adapter by channel name.

Start it:

flowly gateway
flowly gateway --port 18790 --verbose

The bind host comes from config.gateway.host; the listen port comes from the --port flag (default 18790). Setting gateway.port in config alone does not change the listening port via this command — pass --port.

How channels attach at boot

At startup the ChannelManager reads channels.<name>.enabled and instantiates only the channels that are turned on. Each adapter import is guarded, so a missing optional dependency logs a warning instead of crashing the gateway. Enabled adapters and the outbound dispatcher are then started concurrently with the agent loop.

A channel is configured under channels in ~/.flowly/config.json (camelCase keys on disk):

{
  "channels": {
    "telegram": { "enabled": true, "token": "...", "allowFrom": [], "dmPolicy": "pairing" }
  }
}

Channels cli, tui, and desktop are intentionally adapter-less — their replies go out over the gateway WebSocket, not through a channel adapter.

Active channels

Pairing & allowlist security model

Each adapter checks whether a sender is allowed before publishing their message to the bus. The simplest control is the per-channel allowFrom list (an empty list means allow everyone). On top of that, Flowly has a pairing store for granting access without editing config by hand.

How pairing works

• An unauthorized sender (in pairing mode) is issued an 8-character code from an unambiguous alphabet (no 0/O/1/I).
• Codes are stored as pending requests that expire after 1 hour, with a maximum of 3 pending requests per channel.
• You approve a code from the CLI, which moves the sender into the channel's approved allow-store.

Pairing/allow-store files live under ~/.flowly/credentials/:

• {channel}-pairing.json — pending requests
• {channel}-allowFrom.json — approved senders

Pairing commands

flowly pairing list <channel> [--json]
flowly pairing approve <channel> <code> [--notify]
flowly pairing revoke <channel> <user_id>
flowly pairing allowed <channel>

<channel> accepts telegram, whatsapp, discord, slack, or imessage. --notify (on approve) only sends a confirmation DM for Telegram.

Channel status & login (WhatsApp)

flowly channels status
flowly channels login

Related

• Telegram
• Discord
• Slack
• Teams
• WhatsApp
• Web
• Sandbox & approvals
• Service
• Cron
• Slash commands