Connect Discord

Connect Maia to Discord with a bot application. A working setup requires the correct gateway intents, install permissions, and stable user or role IDs for admission.

Before you start

• You need permission to install a bot in the target Discord server.
• Decide which Discord user ID will be Maia's first administrator.
• Store the bot token only in Maia's secret-aware dashboard field or <MAIA_HOME>/.env. Never commit it.

Create the Discord bot

1. Open the Discord Developer Portal, select New Application, name it, and create it.
2. Open Bot, create or reset the bot token, and copy it immediately.
3. Enable Message Content Intent. Enable Server Members Intent when Maia must resolve members or use role-based admission. Save the changes.
4. Under Installation, configure a Guild Install, or use the OAuth2 URL generator with the bot and applications.commands scopes.
5. Grant at least View Channels, Send Messages, Read Message History, Attach Files, Create Public Threads, and Send Messages in Threads. Add Embed Links and Add Reactions for Maia's full response experience.
6. Open the generated install link, choose your server, and authorize the bot.
7. In Discord, enable User Settings > Advanced > Developer Mode. Copy your user ID and any role or channel IDs you intend to use.

Configure Discord in the dashboard

1. Run maia or maia dashboard and open Gateway in the dashboard menu.
2. Select Discord and enter the bot token in the secret-aware field.
3. Add at least one allowed user ID. Add an allowed role only when every intended member of that role will receive Maia governance. Optionally set a home channel.
4. Select Save Discord, then use Start or Restart on the Gateway page.
5. Send the bot a direct message. In a server channel, @mention Maia unless you deliberately configured that channel for free response.

Configure Discord from the CLI

1. Run maia setup gateway and select Discord.
2. Enter the bot token and at least one allowed user ID when prompted.
3. Start Maia in the foreground for the first test:

   maia gateway run

# <MAIA_HOME>/.env
DISCORD_BOT_TOKEN=...
DISCORD_ALLOWED_USERS=284102345871466496,198765432109876543
DISCORD_ALLOWED_ROLES=123456789012345678
DISCORD_HOME_CHANNEL=234567890123456789

# Optional behavior controls
DISCORD_REQUIRE_MENTION=true
DISCORD_FREE_RESPONSE_CHANNELS=234567890123456789
DISCORD_IGNORED_CHANNELS=345678901234567890
DISCORD_AUTO_THREAD=true

Use Discord for governed edit review

A Discord edit review works when gateway admission, Governance permissions, and conversation scope all match:

1. Admit both the employee and the reviewer through DISCORD_ALLOWED_USERS or an intentionally allowed role, then register their stable Discord user IDs in Governance → People. Role admission alone does not grant file access.
2. Give the employee Write after approval on the target file or folder and select at least one named governed manager or administrator. The selected manager receives the path access needed to inspect and execute the reviewed edit; administrators already have global file access.
3. In a server channel Maia can access, have the employee @mention Maia with the edit request. Maia's review response uses the selected Discord user's native <@USER_ID> markup, and the employee may also tag that reviewer. With DISCORD_AUTO_THREAD=true (the default), Maia creates a thread for the response. Keep the employee, reviewer, and Maia in that same thread.
4. Replies in a thread created by Maia do not require another mention. Maia receives each reply as a new turn owned by the authenticated Discord user ID that sent it.
5. Let the reviewer answer naturally. No word such as “approve” or “OK” has special authority: the reviewer may accept, reject, ask a question, or request a different edit. Every file-tool call is authorized again for the person who sent the current message.

Keep automatic Discord threads and shared thread sessions enabled:

# <MAIA_HOME>/.env
DISCORD_AUTO_THREAD=true

# <MAIA_HOME>/config.yaml
gateway:
  thread_sessions_per_user: false

For the matching file policy and the full authorization behavior, see Handle write confirmation.