Skip to main content

​
Credentials

​
1. Create a Slack App

  1. Go to https://api.slack.com/apps
  2. Create New App -> From scratch
  3. Name it (e.g., “Mirage”) and select your workspace

​
2. Configure Bot Permissions

  1. OAuth & Permissions in the left sidebar
  2. Under Bot Token Scopes, add:
    • channels:history - read messages in public channels
    • channels:read - list public channels
    • groups:history, groups:read - private channels (optional)
    • im:history, im:read - direct messages (optional)
    • mpim:history, mpim:read - group direct messages (optional)
    • users:read - the VFS users/ directory
Add chat:write only for the CLI send-message command, and files:write for upload-file. The mount never posts.

​
3. Install to Workspace

  1. Install App in the left sidebar -> Install to Workspace
  2. Authorize the requested permissions
  3. Copy the Bot User OAuth Token (xoxb-...)
Slack’s search.messages API does not accept bot tokens. To use slack search or workspace-level search push-down:
  1. Add search:read under User Token Scopes. For grep and rg, also add channels:read, groups:read, im:read and mpim:read, so Mirage can see which channels and DMs that user’s search covers.
  2. Reinstall or reauthorize the app.
  3. Copy the resulting User OAuth Token (xoxp-...).
Keep using the bot token for normal reads and writes. Mirage uses the optional user token only for Slack search endpoints.

​
5. Set Environment Variables

​
6. Invite the Bot

The bot must be invited to channels it needs to read; a channel it is not in answers Permission denied:
For SDK guides, see Slack (Python) and Slack (TypeScript).