Skip to main content
The bridge is configured via apps/bridge/config.yaml, which defines channel mappings and operational settings. Sensitive values (tokens, passwords) are injected via environment variables — they do not appear in config.yaml. config.yaml is generated from apps/bridge/config.template.yaml by scripts/prepare-config.sh (via envsubst) during just init or just dev/just prod.

​
config.yaml structure

mappings:
  - discord_channel_id: ${BRIDGE_DISCORD_CHANNEL_ID}
    irc:
      server: ${IRC_BRIDGE_SERVER}
      port: ${IRC_TLS_PORT}
      tls: true
      channel: "#general"
    xmpp:
      muc_jid: general@muc.${PROSODY_DOMAIN}

announce_joins_and_quits: true
announce_extras: false

identity_cache_ttl_seconds: 3600
avatar_cache_ttl_seconds: 86400
xmpp_avatar_base_url: ${XMPP_AVATAR_BASE_URL}
irc_puppet_idle_timeout_hours: 24
irc_puppet_postfix: ""

irc_throttle_limit: 10
irc_message_queue: 30
irc_rejoin_delay: 5
irc_auto_rejoin: true

# Set false for dev with self-signed certs; true for production
irc_tls_verify: ${IRC_TLS_VERIFY}

irc_relaymsg_clean_nicks: false
irc_redact_enabled: false

irc_use_sasl: false
irc_sasl_user: ""
irc_sasl_password: ""
Warning: irc_tls_verify defaults to false in development (self-signed certificates). You must set BRIDGE_IRC_TLS_VERIFY=true in .env before any public deployment.

​
Environment variables

VariableDescriptionRequired
BRIDGE_DISCORD_TOKENDiscord bot tokenYes (if Discord adapter enabled)
BRIDGE_DISCORD_CHANNEL_IDDiscord channel snowflake ID to bridgeYes
IRC_BRIDGE_SERVERIRC server hostname (use Docker service name internally)Yes
IRC_TLS_PORTIRC server port (default: 6697)No
BRIDGE_IRC_NICKIRC nick for the bridge botNo
BRIDGE_IRC_OPER_PASSWORDIRC oper password for the bridgeNo
BRIDGE_IRC_TLS_VERIFYOverride irc_tls_verify (true/false)No
BRIDGE_XMPP_COMPONENT_JIDXMPP component JID (for component protocol)Yes (if XMPP enabled)
BRIDGE_XMPP_COMPONENT_SECRETXMPP component secretYes (if XMPP enabled)
BRIDGE_XMPP_COMPONENT_SERVERXMPP server hostname for component connectionNo
BRIDGE_XMPP_COMPONENT_PORTXMPP component port (default: 5347)No
BRIDGE_PORTAL_BASE_URLPortal API base URL for identity resolutionNo
BRIDGE_PORTAL_TOKENPortal API authentication tokenNo

​
Portal integration

The bridge supports an optional Portal identity service for unified user profiles across platforms. When configured, the bridge resolves user identities across Discord, IRC, and XMPP so that bridged messages display consistent nicknames. To enable Portal integration, set both environment variables: 
BRIDGE_PORTAL_BASE_URL=https://portal.atl.tools
BRIDGE_PORTAL_TOKEN=your-portal-api-token
Token mapping: Use the same secret for both sides. Set BRIDGE_PORTAL_TOKEN (atl.chat bridge) and BRIDGE_SERVICE_TOKEN (Portal) to the same value. The bridge sends this token as a Bearer credential; Portal expects it in BRIDGE_SERVICE_TOKEN.
When Portal is not configured, the bridge runs in dev mode with fallback nick resolution — bridged messages use the originating platform’s display name with a platform suffix. The Portal client includes:
  • Automatic retries with exponential backoff (via tenacity)
  • TTL-based identity cache (default: 1024 entries) to reduce API calls
  • Lookup methods: discord_to_irc, discord_to_xmpp, irc_to_discord, xmpp_to_discord

​
Channel mapping format

Channel mappings connect a Discord channel to an IRC channel and/or an XMPP MUC room. Each mapping is defined in the mappings list within the config: 
mappings:
  - discord_channel_id: "123456789012345678" # Discord channel snowflake ID
    irc:
      server: "irc.atl.chat" # IRC server hostname
      port: 6697 # IRC server port
      tls: true # Use TLS connection
      channel: "#general" # IRC channel name
    xmpp:
      muc_jid: "general@muc.atl.chat" # XMPP MUC room JID
Each mapping requires a discord_channel_id. The irc and xmpp sections are optional — you can bridge Discord to IRC only, Discord to XMPP only, or all three platforms together.

​
IRC target fields

FieldTypeDescription
serverstringIRC server hostname
portintegerIRC server port (default: 6667)
tlsbooleanUse TLS for the connection
channelstringIRC channel name (including # prefix)

​
XMPP target fields

FieldTypeDescription
muc_jidstringFull JID of the XMPP MUC room

​
Multiple mappings

You can define multiple mappings to bridge several channels: 
mappings:
  - discord_channel_id: "111111111111111111"
    irc:
      server: "irc.atl.chat"
      port: 6697
      tls: true
      channel: "#general"
    xmpp:
      muc_jid: "general@muc.atl.chat"

  - discord_channel_id: "222222222222222222"
    irc:
      server: "irc.atl.chat"
      port: 6697
      tls: true
      channel: "#support"
    # No XMPP target — this channel bridges Discord <-> IRC only