Run OpenGauss as a Persistent Messaging Bot Gateway

The OpenGauss messaging gateway is a long-running process that connects the Gauss agent to one or more messaging platforms simultaneously. When a user sends a message, the gateway routes it to a dedicated Gauss session, runs the agent loop, and delivers the response back — all without you needing to keep a terminal open. Session state is stored in a shared SQLite database so conversations persist across gateway restarts.

Starting the gateway

gauss gateway
# or equivalently:
gauss gateway start

Gauss reads platform credentials from ~/.gauss/.env and activates any platform whose token is present. You can configure tokens interactively with gauss setup or by editing ~/.gauss/.env directly.

Supported platforms

Create a bot with @BotFather to get a token, then save it:

# ~/.gauss/.env
TELEGRAM_BOT_TOKEN=7123456789:AAF...
TELEGRAM_ALLOWED_USERS=123456789,987654321

TELEGRAM_ALLOWED_USERS is a comma-separated list of Telegram numeric user IDs. Get your own ID from @userinfobot.Run gauss setup to configure both values interactively.

Create a bot application in the Discord Developer Portal, generate a bot token, and invite the bot to your server with the required permissions.

# ~/.gauss/.env
DISCORD_BOT_TOKEN=MTIzNDU2Nzg5...
DISCORD_ALLOWED_USERS=123456789012345678,987654321098765432

By default the bot requires an @mention in server channels. To allow responses without a mention in specific channels, set discord.free_response_channels in ~/.gauss/config.yaml:

discord:
  require_mention: true
  free_response_channels: "111222333444,555666777888"
  auto_thread: true

Create a Slack app at api.slack.com/apps. You need two tokens:

Bot token (xoxb-) — from OAuth & Permissions after installing the app. Required scopes: chat:write, app_mentions:read, channels:history, groups:history, im:history, im:read, im:write, users:read, files:write.
App token (xapp-) — from Basic Information → App-Level Tokens. Enable Socket Mode and subscribe to events: message.im, message.channels, message.groups, app_mention.

# ~/.gauss/.env
SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...
SLACK_ALLOWED_USERS=U012AB3CD

WhatsApp uses a QR-code pairing flow. Run the guided setup command:

gauss whatsapp

Gauss walks you through scanning the QR code to pair your WhatsApp account with the local bot process. No separate bot token is required; the session credentials are saved automatically.Set an allowed-users allowlist after pairing:

# ~/.gauss/.env
WHATSAPP_ALLOWED_USERS=+15551234567,+447700900000

OpenGauss integrates with Signal via the signal-cli-rest-api container. Start the REST API container separately, then point Gauss at it:

# ~/.gauss/.env
SIGNAL_CLI_REST_API_URL=http://localhost:8080

The gateway will connect to the Signal REST API and relay messages through it.

Configure your IMAP and SMTP credentials to receive and send email via the gateway. Add the following to ~/.gauss/.env:

EMAIL_IMAP_HOST=imap.example.com
EMAIL_IMAP_PORT=993
EMAIL_SMTP_HOST=smtp.example.com
EMAIL_SMTP_PORT=587
EMAIL_ADDRESS=gauss-bot@example.com
EMAIL_PASSWORD=your-app-password

The gateway polls the IMAP inbox for new messages and replies via SMTP.

OpenGauss integrates with Home Assistant via REST tools and a WebSocket gateway. Set your Home Assistant URL and long-lived access token:

# ~/.gauss/.env
HASS_SERVER=http://homeassistant.local:8123
HASS_TOKEN=eyJhbGci...

The gateway connects over WebSocket to receive events and can call Home Assistant services through the built-in REST tools. Run gauss setup to configure both values interactively.

Allowed users and access control

Every platform supports a per-platform allowlist that restricts which users can interact with the bot:

Environment variable	Platform
`TELEGRAM_ALLOWED_USERS`	Comma-separated Telegram user IDs
`DISCORD_ALLOWED_USERS`	Comma-separated Discord user IDs
`SLACK_ALLOWED_USERS`	Comma-separated Slack user IDs
`WHATSAPP_ALLOWED_USERS`	Comma-separated phone numbers (E.164 format)

To allow all users on all platforms (not recommended for public bots), set:

GATEWAY_ALLOW_ALL_USERS=true

Configure allowlists before exposing your bot to public channels or groups. Without an allowlist, any user who discovers your bot can run arbitrary Gauss agent sessions with access to your configured tools and terminal backend.

Session isolation

Each user (and, on platforms like Discord that support threads, each channel or thread) gets a fully isolated Gauss session. Session history, memory, and in-progress tool calls are kept separate. All sessions are stored in a shared SQLite database under ~/.gauss/sessions/, which means:

Sessions survive gateway restarts.
All platforms share the same session storage, so a single Gauss instance can serve Telegram and Discord users simultaneously.
The /resume command lets users switch to a named previous session from within a messaging conversation.

All platforms share the same SQLite session database. This means /sessions, /resume, and memory are consistent regardless of which messaging platform a user connects from — as long as they use the same user ID.

Background process notifications

When the agent spawns background processes (for example, a long-running lake build), the gateway can notify users of progress or completion. Configure the notification level in ~/.gauss/config.yaml:

display:
  background_process_notifications: result   # all | result | error | off

Value	Behavior
`all`	Send a message for every status update
`result`	Send a message only when the process finishes (success or error)
`error`	Send a message only if the process fails
`off`	No notifications

Per-platform tool configuration

Use gauss tools to open the interactive curses UI for enabling and disabling individual tools per platform:

gauss tools

This is useful when you want to restrict what the bot can do on public channels — for example, disabling the terminal tool for all users on a Telegram bot while keeping it available in the CLI.

Installing as a systemd service

To keep the gateway running permanently and restart it automatically on reboot, install it as a systemd service:

gauss gateway install

This generates and installs a systemd unit file. After installation:

# Start the service
systemctl --user start gauss-gateway

# Enable on boot
systemctl --user enable gauss-gateway

# View logs
journalctl --user -u gauss-gateway -f

To update Gauss while the service is running, use:

gauss update

gauss update pulls the latest version and restarts the gateway service automatically.

Get Started

Core Concepts

Configuration

Guides

Run OpenGauss as a Persistent Messaging Bot Gateway

Starting the gateway

Supported platforms

Allowed users and access control

Session isolation

Background process notifications

Per-platform tool configuration

Installing as a systemd service

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

Guides

Documentation Index

​Starting the gateway

​Supported platforms

​Allowed users and access control

​Session isolation

​Background process notifications

​Per-platform tool configuration

​Installing as a systemd service

Build docs developers (and LLMs) love

Starting the gateway

Supported platforms

Allowed users and access control

Session isolation

Background process notifications

Per-platform tool configuration

Installing as a systemd service