Skip to main content

Setup

This guide gets the bot running against your UIGraph instance, from creating the Slack app to filling in every value. You don't need to be a developer to follow it.

What you'll need​

  • A Slack workspace where you're allowed to create and install apps.
  • A running UIGraph deployment: its API and MCP services, reachable from wherever you run the bot.
  • An API key for an AI model provider (for example OpenAI, Anthropic, or any OpenAI-compatible endpoint). See AI Providers.
  • Docker, or a Node.js runtime if you prefer to run the bot directly.

1. Create the Slack app​

Go to api.slack.com/apps → Create New App → From an app manifest, pick your workspace, and paste the manifest below (change the name and description if you like):

display_information:
  name: UiGraph
  description: Ask questions about your architecture, right from Slack.
  background_color: '#1a1a2e'
features:
  bot_user:
    display_name: UiGraph
    always_online: true
oauth_config:
  scopes:
    bot:
      - app_mentions:read
      - assistant:write
      - channels:history
      - channels:manage
      - channels:read
      - chat:write
      - files:write
      - groups:write
      - im:write
      - mpim:write
      - reactions:write
      - emoji:read
      - im:read
      - files:read
      - groups:read
      - team:read
      - users:read
      - users:read.email
      - users.profile:read
      - reactions:read
      - mpim:read
      - metadata.message:read
      - remote_files:read
      - remote_files:write
      - remote_files:share
      - im:history
      - groups:history
      - mpim:history
      - incoming-webhook
settings:
  event_subscriptions:
    bot_events:
      - app_mention
      - message.im
  interactivity:
    is_enabled: true
  socket_mode_enabled: true

The bot uses Socket Mode, which means it opens an outbound connection to Slack instead of receiving public web requests. You never have to expose a public URL or open a port to the internet.

The files:read and files:write scopes let the bot read files people share with it (for example an image of a diagram) and send files back. The *:history scopes let it read the thread it's replying in, and the users:* scopes let it resolve who is asking. If you add or change scopes later, you must reinstall the app to your workspace for the change to take effect.

2. Get your two Slack values​

After creating the app:

  1. Bot token, go to OAuth & Permissions and click Install to Workspace. Copy the Bot User OAuth Token (starts with xoxb-). This is your SLACK_BOT_TOKEN.
  2. App token, go to Basic Information → App-Level Tokens, generate a token with the connections:write scope, and copy it (starts with xapp-). This is your SLACK_APP_TOKEN.

3. Get your UIGraph values​

Connect the bot to your UIGraph instance:

  1. API and MCP URLs, the base URLs of your UIGraph API and MCP services. These are your UIGRAPH_API_URL and UIGRAPH_MCP_URL. On a local setup they might look like http://localhost:2181 and http://localhost:2187; inside a Docker network they might look like http://uigraph-api:8080 and http://uigraph-mcp:8080.
  2. Access token, a service account API key / access token for the organization the bot should answer for (starts with uig_), created from your UIGraph organization settings. This is your UIGRAPH_TOKEN. It's shown only once, so copy it right away.

The access token scopes every answer to the right organization, and the bot only ever reads your architecture data through it.

4. Choose your AI model​

The bot needs an AI model to reason over your architecture data. At minimum you'll set:

  • AI_PROVIDER_API_KEY: your provider's API key
  • AI_PROVIDER_MODEL: the model to use (for example gpt-4o or claude-sonnet-5)

By default the bot talks to any OpenAI-compatible endpoint, in which case you also set AI_PROVIDER_API_URL. To use a specific provider instead (OpenAI, Anthropic, Google, and many more), set AI_PROVIDER_NPM.

The full list of supported providers, model examples, and optional settings are on their own page: AI Providers.

5. Configure and run​

Put your values in a .env file. A minimal example:

SLACK_BOT_TOKEN="xoxb-…"
SLACK_APP_TOKEN="xapp-…"

UIGRAPH_API_URL="http://localhost:2181"
UIGRAPH_MCP_URL="http://localhost:2187"
UIGRAPH_TOKEN="uig_…"

AI_PROVIDER_API_URL="https://api.openai.com/v1"
AI_PROVIDER_API_KEY="sk-…"
AI_PROVIDER_MODEL="gpt-4o"

See Environment variables for the complete list.

With Docker​

docker build -t uigraph-slack .
docker run --rm --env-file .env uigraph-slack

Without Docker​

pnpm install
pnpm start

6. Check it works​

Invite the bot to a channel with /invite @uigraph, then mention it with a question:

@uigraph what services depend on the billing database?

You should get a threaded reply within a few seconds. You can also send it a direct message, no mention needed there.

tip

If nothing happens, check the bot's logs. The two most common startup problems are a missing or mistyped token and an AI model that isn't configured correctly, the logs print a clear message for both.