Messaging Gateway Guide

The Arcen messaging gateway allows you to control and interact with your AI agent remotely via chat applications (Telegram, Slack, Discord, Signal, etc.) while it runs securely on your host machine or server.

1. Supported Platforms & Adapters

Gateway platform adapters reside in gateway/platforms/. Each platform implements a unified adapter interface handling incoming messages, routing commands, and streaming back responses.

The gateway supports:

Telegram: Supports bot polling or webhooks. Configured with a TELEGRAM_BOT_TOKEN.
Slack: Integrates via Socket Mode or HTTP webhooks. Configured with SLACK_BOT_TOKEN and SLACK_APP_TOKEN.
Discord: Logged in via bot websocket tokens.
WhatsApp / Signal / Matrix: Matrix homeserver endpoints and local Signal CLI socket wrappers.
Webhooks & HTTP API: Exposes an HTTP endpoint to trigger agents from systems like Home Assistant.

2. Setting Up a Platform

To set up a messaging connection, run the gateway wizard:

arcen gateway setup

The wizard prompts you for target platforms and saves the credentials into your ~/.arcen/.env file. For example, a typical Telegram configurations block in .env looks like:

TELEGRAM_BOT_TOKEN=1234567890:ABCdefGhIJKlmNoPQRsTUVwxyZ
TELEGRAM_ALLOWED_USER_IDS=987654321,11223344

To run the gateway listener process:

arcen gateway start

3. Working Directory & Tool Bridging

Because the messaging gateway runs as a background process independent of your active shell, it resolves execution paths using config.yaml:

# ~/.arcen/config.yaml
terminal:
  cwd: /Users/aditya/Coding/workspace

At startup, the gateway bridges terminal.cwd to the TERMINAL_CWD environment variable. Any child terminal tools spawned by the agent will automatically execute in this path.

4. Gateway Slash Commands & Config Gating

By default, slash commands (such as /compress, /usage, etc.) are processed by the central command registry.

However, some commands are CLI-only unless enabled via a config gate:

Config gating uses the gateway_config_gate attribute on a CommandDef.
For example, if a command has gateway_config_gate: "display.tool_progress_command", the gateway will block execution of that command unless display.tool_progress_command is set to true in your config.yaml.
Config-gated commands are loaded in GATEWAY_KNOWN_COMMANDS so the parser can identify them, but they are filtered out of help outputs unless their gate is active.

5. Running Multiple Gateway Sessions

You can run multiple gateway processes by defining separate config homes using profiles. Ensure that only one profile manages active task distribution to prevent conflict:

# Profile 1 (Main Task Dispatcher)
kanban:
  dispatch_in_gateway: true

# Profile 2 (Worker Session)
kanban:
  dispatch_in_gateway: false

Keep dispatch_in_gateway: true enabled only on a single, primary coordinator session.