apps/bots/ and all talk to the same GAIA API, so a user’s conversations, todos and workflows are the same on every platform.
This section is for running and changing the bots from source. To add the bots to a self-hosted instance, see Self-Hosting: Bots. To chat with GAIA on a platform as a user, see the guides for Slack, Discord, Telegram, WhatsApp or iMessage.
How the bots work
Each bot is a thin TypeScript process that forwards a platform’s messages to the GAIA API, then renders the reply in the platform’s own format: for example embeds on Discord, Block Kit on Slack, Markdown on Telegram and plain text on iMessage. The shared logic (commands, streaming, formatting, the API client) lives inlibs/shared/ts/src/bots/, so most changes are made once for every platform.
Users link their platform account to their GAIA account once, with the /auth command.
Each bot serves
GET /health on its port. BOT_SERVER_PORT overrides the port.
Shared setup
Do this once, whichever bot you work on.1
Run GAIA
Follow Set up GAIA for development until
mise dev --agent is running.2
Create the bots' env file
All bots read one shared file, Then set the four values every bot needs:
apps/bots/.env:A bot refuses to start while any of these four is missing.
3
Give the API the same secrets
In
apps/api/.env, set GAIA_BOT_API_KEY to the same value: the API rejects bot requests whose key doesn’t match. Set BOT_LOG_HASH_SECRET to the same value too, so a user’s hashed id matches in the API’s and the bots’ logs. Also set BOT_SESSION_TOKEN_SECRET to a third value from openssl rand -hex 32: the API uses it to sign the bots’ session tokens. Restart mise dev after editing.4
Add the platform's credentials
Follow the page for your platform below. It adds that platform’s token to
apps/bots/.env.5
Start the bot
RABBITMQ_URL is already set in the template. Keep it: without it the bot can still answer messages, but it never receives the replies and reminders the API sends later on its own, such as the result of a long background task.
Per-bot files (apps/bots/<platform>/.env) are still read, after the shared file, for Docker and older setups. Prefer the shared file: when both set a variable, the shared file wins.
Platform guides
Discord
Discord application, gateway intents, slash commands, account linking
Slack
Slack app with Socket Mode, no public URL required
Telegram
BotFather setup with long polling, no webhook required
Kapso and the Meta Cloud API, through a signed webhook
iMessage
Photon Spectrum, through a signed webhook
Test without a platform account
bot-harness (apps/bots/harness) is a simulated platform. It sends a message through the real shared bot code to your running API and records the reply, with no Discord, Slack or Telegram account:
apps/bots/.env. apps/bots/harness/README.md covers scenarios and flags. The bots’ unit tests run with mise test:bots.
Commands
Every platform has the same core commands (/gaia, /todo, /workflow, /conversations, /auth). The full list, with platform differences, is in the Commands reference.
