Skip to content

Connect a bot ​

The connector maps Mattermost threads to Orpheus sessions and returns messages and files to the original thread.

Create the bot ​

  1. Enable bot account creation in Mattermost integration settings.
  2. Open Integrations → Bot Accounts and create a bot with a recognizable username, such as orpheus.
  3. Save the generated token in .env as MATTERMOST_BOT_TOKEN.
  4. Set the Mattermost address and token variable name in the workflow.
  5. Add the bot to the relevant team and channels. For private channels, first configure and load a matching workflow.
yaml
mattermost:
  base_url: https://chat.example.com
  token_env: MATTERMOST_BOT_TOKEN

Supply the token to both connector and worker. Include MATTERMOST_BOT_TOKEN in a service definition or HARNESS_ENV_ALLOWLIST on API and worker because file hooks use it. The quick-start catalog already defines this name.

The quick-start service can also be selected in Space, granting that agent the bot token's read and post permissions. To keep the token out of service selectors, keep its name in HARNESS_ENV_ALLOWLIST and omit it from the catalog. This does not limit trusted API clients or workflows that explicitly select ENV names. See request scopes.

The connector discovers the bot ID and username from its token. Workflows sharing a bot must use the same token variable name. Different bots can have independent workflow sets.

Check with docker compose run --rm --no-deps mattermost validate, then start the connector and request /readyz. Validation checks local configuration. Startup checks server connectivity and credentials.

Mattermost bot accounts · Quick start