Skip to main content

LibreChat is joining ClickHouse. Learn more

LibreChat

Slack Channel Gateway (Beta)

Deploy the Slack gateway for organization workspaces or a manually configured connection.

Run the Slack gateway alongside LibreChat to connect agents to Slack. This guide covers deployment. Once the gateway is ready, follow Agent Channels to connect a Slack app, assign an agent, and link your account.

Choose a setup path:

Using Helm? Go to Kubernetes and Helm. Building from source? See From source.

Beta and opt-in

Use matching LibreChat and gateway releases that include Channels. Ordinary LibreChat does not need the gateway; enabling Channels requires a transaction-capable database and the indexes described below.

Configuration and prerequisites

Both setup paths need the following. In shared mode, one gateway serves multiple installations while each person keeps their own account and tool credentials:

  • A verified transaction-capable database with the indexes below.
  • Role permissions to use Agents and query them through Remote Agents (API) for participants, plus Agent sharing or administrator management access for setup. Sharing does not require permission to edit the Agent.
  • API-key authentication enabled for the gateway's bound execution credential.
  • A private CHANNEL_SERVICE_TOKEN with the same value in the API and gateway. Keep it server-side. It authenticates the gateway, and cannot be used as a browser token or general Agent API key.
  • A trusted DOMAIN_CLIENT for account-link and owner-review URLs. Organization workspaces also require the public HTTPS addresses described below.

Linking an account does not grant Agent access, new tools or offline access to connected services. See the channel configuration reference for policy limits and defaults.

Database requirement

Check your database before enabling Channels. Durable Channels and stored background Responses need both transactions and the required indexes, including partial indexes.

DatabaseWhat this means for setup
MongoDB replica set or another verified transaction-capable deploymentCheck that the required indexes are supported too.
Standalone MongoDB or FerretDB 2.7Can run LibreChat without this durable feature. A different database setup is needed for Channels and stored background Responses.
Amazon DocumentDB 4.0Partial indexes are not supported, so it cannot run this gateway.

Other MongoDB-compatible engines need compatibility validation before use. Unsupported channel writes return transactions_unavailable, and the Agent Builder explains the setup requirement. Transactional reads use the primary even when your connection normally prefers secondary reads.

Organization workspaces

Use this mode for organization-owned Slack apps managed in LibreChat. An operator deploys one shared gateway; organization administrators then register apps and install workspaces through Account settings. Each app supports one active workspace. No per-workspace gateway process or deployment secret is needed.

One-time operator setup

Prepare the database and service token. Meet the prerequisites, including transaction-capable MongoDB. Generate a private service token with openssl rand -hex 32 and use the same value in the API and gateway.

Set the public addresses. Configure public HTTPS DOMAIN_SERVER and DOMAIN_CLIENT in .env, replacing the localhost defaults. Both are required. Include the application base path when present and remove any surrounding whitespace.

If callbacks use a separate public origin, set SLACK_GATEWAY_URL to it. Otherwise callbacks use DOMAIN_SERVER. The shared deployment opt-in rejects local addresses.

Route Slack callbacks to the gateway. Forward /slack/events/ and /slack/interactions/, including their organization/app suffixes. If callbacks use DOMAIN_SERVER, route those paths on the application origin to the gateway too.

The gateway container listens on port 8080. The shared Compose overlay publishes it at 127.0.0.1:3081 for a host-level HTTPS proxy.

Route the application and OAuth callback to LibreChat. Keep gateway health and metrics private. This deployment step does not need Slack dashboard access or app credentials.

For Docker Compose with a separate gateway origin, add these values to your .env file. Keep the file out of version control:

SLACK_GATEWAY_URL=https://slack.example.com
CHANNEL_SERVICE_TOKEN=<private random token, at least 32 characters>
DOMAIN_SERVER=https://chat.example.com
DOMAIN_CLIENT=https://chat.example.com
LIBRECHAT_IMAGE_TAG=<published release containing organization workspaces>

Already have MongoDB data?

The command below includes the replica overlay for a fresh local database. Read Existing local data before converting an existing installation. For a verified external database, omit that overlay and supply your normal connection configuration.

With .env and librechat.yaml prepared, start the release-matched application and shared gateway:

docker compose -f docker-compose.yml -f docker-compose.channels.yml \
  -f docker-compose.slack-workspaces.yml -f docker-compose.mongo-replica.yml \
  --profile channels up -d api meilisearch channel-gateway

Use the same Compose project and files for subsequent commands.

You still need to configure your HTTPS proxy and trusted certificate. A host-level proxy forwards the two Slack paths to http://127.0.0.1:3081, preserving the organization/app suffixes. Set CHANNEL_GATEWAY_PORT in .env to change that loopback port. A proxy in the same Compose network can forward to http://channel-gateway:8080 instead.

The shared overlay supplies SLACK_WORKSPACES_ENABLED=true, which enables webhook Channels, shared app installation and stored background Responses while retaining unrelated YAML policy, limits and explicit API authentication settings. Slack app credentials are entered by organization admins through the UI and stored encrypted; they are not deployment environment variables or YAML fields. With the flag unset or false, YAML continues to control the feature. Choosing shared setup changes the deployment's channel transport to webhook; existing bound connections must use matching webhook configuration. Manual Socket Mode remains available when using the manual setup instead.

No CHANNEL_ID, CHANNEL_TENANT_ID or app-level SLACK_APP_TOKEN is needed in shared mode. The gateway receives its service token and private runtime policy; app client credentials stay in LibreChat, and installed bot tokens are encrypted in the database. For an unreleased source checkout, add docker-compose.channels-build.yml after docker-compose.channels.yml on every command and use up -d --build instead of expecting an unpublished release image.

Before connecting Slack, check gateway readiness. Then continue with app registration.

Run the Slack gateway

Use this manual setup for one tenant and connection. First enable Channels and background Responses in librechat.yaml; both default to false:

endpoints:
  agents:
    remoteApi:
      background:
        enabled: true
    channels:
      enabled: true
      transport: socket_mode

The transport option accepts socket_mode (default) or webhook. Manual connections generate a matching Slack manifest; organization workspaces use the webhook setup above. Selecting a transport does not deploy a receiver. Webhook manifests require an HTTPS gatewayUrl without credentials, a query, or a fragment. The gateway loads this policy from LibreChat before selecting ingress. SLACK_TRANSPORT is an optional deployment assertion; if supplied, it must match the server-selected mode. Missing or unsupported gateway policy prevents startup.

Create and activate the manual Slack connection before starting its gateway. The connection ID is needed below. For a container deployment, skip to Docker Compose; a source process requires Node.js 24+.

From source

The gateway uses Slack's official Node SDKs and calls LibreChat over HTTP. It does not connect directly to MongoDB. In shared mode, the same source entry point works without the bound tenant/connection IDs or app-level token; supply the internal API URL and service token instead.

From a LibreChat source checkout containing packages/channel-gateway:

npm ci
npm run build:packages
npm run build --workspace @librechat/channel-gateway
node --env-file=/secure/channel-gateway.env packages/channel-gateway/dist/main.cjs

npm run backend:dev starts only LibreChat; it does not start the gateway. Build the application using LibreChat's normal development setup and run the gateway separately. If you reuse the application's .env, set the gateway port explicitly: PORT=8080 node --env-file=.env packages/channel-gateway/dist/main.cjs. This avoids binding the gateway to the application's port.

Supply the environment file through your normal secret-management process. Do not commit it. A Socket Mode configuration is:

LIBRECHAT_INTERNAL_URL=http://127.0.0.1:3080
CHANNEL_SERVICE_TOKEN=<same server-side token configured in LibreChat>
CHANNEL_TENANT_ID=_
CHANNEL_ID=<connection ID from the Agent builder>
SLACK_TRANSPORT=socket_mode
SLACK_APP_TOKEN=<app-level token with connections:write>

LIBRECHAT_INTERNAL_URL must be reachable from the gateway process. For example, 127.0.0.1 refers to the gateway's own container when running inside a container. Use the exact tenant ID for a multi-tenant deployment; use _ only for a single-tenant deployment without a tenant ID. The gateway obtains the bot token and signing secret from LibreChat's authenticated connection bundle, so those values do not need separate gateway environment variables.

For Socket Mode, enable Socket Mode for the same Slack app and create an app-level token with connections:write. Keep that token only in the gateway's secret configuration. No public callback URL is needed, but the gateway needs outbound access to Slack and LibreChat.

For webhooks, set SLACK_TRANSPORT=webhook instead and omit SLACK_APP_TOKEN. Put the gateway behind HTTPS and set these Slack request URLs, replacing the placeholders with the configured, URL-encoded IDs:

Events:       https://gateway.example.com/slack/events/<tenantId>/<channelId>
Interactivity: https://gateway.example.com/slack/interactions/<tenantId>/<channelId>

The webhook receiver verifies Slack signatures using the connection's signing secret. Keep LibreChat's channel service routes private to trusted integrations. Expose only the required Slack callback paths publicly; keep health and metrics endpoints on an internal network.

Docker Compose

The optional docker-compose.channels.yml overlay pulls release-matched LibreChat and gateway images. Set LIBRECHAT_IMAGE_TAG in .env to the release tag you are installing (including -rcN for a release candidate); both images use that same tag. If omitted, both use the latest stable release. Images are published for Linux AMD64 and ARM64 when the corresponding LibreChat release is published. A tag predating Agent Channels does not contain a gateway image. The separate docker-compose.mongo-replica.yml overlay initializes a single local MongoDB replica member and waits for a writable primary before the application starts. The gateway waits for application health, then authenticates its channel binding and selected Slack transport. Neither service is added to the default stack automatically.

For a fresh local database, run these commands from the LibreChat repository root:

  1. Prepare .env and librechat.yaml using the normal LibreChat setup and the channel policy above. Set LIBRECHAT_IMAGE_TAG to the published LibreChat release containing Channels. Generate a private service token with openssl rand -hex 32 and set CHANNEL_SERVICE_TOKEN in .env. Keep the same Compose files and project name on subsequent commands.

  2. Pull and start the application and its dependencies:

    docker compose -f docker-compose.yml -f docker-compose.channels.yml \
      -f docker-compose.mongo-replica.yml up -d --pull always api meilisearch
  3. Sign in, save an Agent, and set up its Slack channel. Enter the bot token in the Agent builder. Set CHANNEL_ID in .env to the resulting connection ID. CHANNEL_TENANT_ID defaults to _ for an ordinary OSS installation; supply the actual tenant ID for a tenant-scoped installation. For Socket Mode, also set SLACK_APP_TOKEN to the matching app-level token with connections:write.

  4. Start the gateway:

    docker compose -f docker-compose.yml -f docker-compose.channels.yml \
      -f docker-compose.mongo-replica.yml --profile channels up -d --pull always channel-gateway
  5. Check readiness and startup errors:

    docker compose -f docker-compose.yml -f docker-compose.channels.yml \
      -f docker-compose.mongo-replica.yml --profile channels ps -a
    docker compose -f docker-compose.yml -f docker-compose.channels.yml \
      -f docker-compose.mongo-replica.yml --profile channels logs --tail=100 api mongodb-init channel-gateway

mongodb-init exiting with status 0 is expected. Check that the application and gateway are running and healthy. Missing service/app bindings prevent gateway startup.

Activation checks your Slack credentials. Check gateway readiness too, then link your account and send the bot a new request to test the connection.

The overlay points LIBRECHAT_INTERNAL_URL at http://api:${PORT:-3080} on the Compose network. The gateway listens on container port 8080, with no published host ports. Socket Mode needs no inbound port; webhooks need an HTTPS reverse proxy forwarding the required callback paths to channel-gateway:8080. The gateway runs as a non-root user with a read-only filesystem and dropped capabilities.

For an existing external transaction-capable database, omit the local MongoDB replica overlay and provide the application connection through your normal Compose override. The base Compose file sets the API service's MONGO_URI, so changing only .env does not replace that service environment entry. Never run the local initializer against an external database.

A separate gateway environment file can be supplied through --env-file .env --env-file /secure/channel-gateway.env. Keep CHANNEL_SERVICE_TOKEN identical in LibreChat's own .env; Compose substitution does not update the file mounted into the application.

For development or an unreleased checkout, add -f docker-compose.channels-build.yml immediately after -f docker-compose.channels.yml on every Compose command. This explicitly builds both services from the checkout instead of using release images. Use up -d --build instead of up -d --pull always on that path. The normal release path needs no local Node.js installation or image build.

To build only the gateway image, use the repository root as its build context:

docker build -f packages/channel-gateway/Dockerfile \
  -t librechat-channel-gateway:local .

Existing local data

Back up the database, stop LibreChat and every gateway/worker that writes to it, then stop the database before applying the replica overlay. Retain the existing data-node directory; do not delete it or remove its volume. Start with that same data directory and the overlays above. Initialization preserves existing documents and only initializes an unconfigured local rs0 member at mongodb:27017. It refuses a different replica configuration rather than silently reconfiguring it. Verify existing users/history before enabling the gateway, and retain the overlay on future restarts.

A single local replica member enables transactions but does not provide high availability. The overlay follows the base development Compose authentication/network settings; it is not a production replica-set recipe. For authenticated, multi-member or production deployments, use the MongoDB conversion procedure and your deployment's backup/security practices.

Gateway settings

Environment variableDefaultPurpose
PORT8080Gateway HTTP port
LISTEN_HOST0.0.0.0Listen address; use loopback for a host-only local process
LIBRECHAT_INTERNAL_URLhttp://localhost:3080LibreChat service origin
CHANNEL_SERVICE_TOKENRequiredShared server-side service-boundary token
CHANNEL_TENANT_IDRequired in manual modeExact connection tenant; _ for single-tenant deployments
CHANNEL_IDRequired in manual modeConnection ID, not the Slack channel ID or Agent ID
SLACK_TRANSPORTServer policyOptional assertion: webhook or socket_mode; must match the server policy
SLACK_APP_TOKENRequired for Socket ModeApp-level token for the same Slack app
APP_TITLELibreChatApplication name in browser-review button labels, such as “Open in LibreChat”
API_CALL_TIMEOUT_MS10000Timeout for individual service and Slack API calls
AGENT_INVOKE_TIMEOUT_MS120000Timeout for initial background Response submission, not the full Agent run

SLACK_API_BASE_URL defaults to https://slack.com/api/; leave it unchanged outside controlled tests. Ingress mode, native sessions, lifecycle reactions, signature tolerance and reconnect pacing come from endpoints.agents.channels in librechat.yaml, not process feature flags. Actor-bound durable execution cannot be disabled.

Verify the gateway

Check readiness before moving on to Slack setup. The gateway exposes these internal endpoints:

EndpointWhat it checks
/livezThe HTTP process is alive.
/readyz, /healthzStartup and transport readiness.
/metricsPrometheus metrics.

Keep these routes private. Use the same deployment configuration for readiness checks and logs that you used to start the gateway. For shared Compose, include docker-compose.slack-workspaces.yml and any database/build overlays too.

If the ingress mode or Socket app binding does not match, the gateway reports unready. Restart gateway replicas after changing the ingress mode or Socket app identity.

Activation checks your Slack credentials. To test the complete connection, link your account, then send the bot a new request.

If gateway requests to LibreChat return 401, check that both processes use the same CHANNEL_SERVICE_TOKEN and that LIBRECHAT_INTERNAL_URL reaches the intended instance. This is separate from Slack callback signature verification.

To stop the optional gateway, use the same Compose project and file list with stop channel-gateway, or disable channelGateway.enabled in Helm and remove the shared API opt-in. Keep the database configuration: stopping the gateway does not require converting or removing its data.

Native Agent UI and final replies

By default, Slack shows a working message with Stop and, when needed, Review controls while the agent runs. The final answer is posted after generation.

Replies can include code, tables, links, file attachments, and time and cost details when available. Missing costs are not estimated.

To opt into Slack's native Agent sessions, enable Agent mode in the Slack app, add the assistant:write bot scope, and verify that agent_session_stopped is subscribed. Add that event if missing; the generated manual manifest already includes it, while the basic organization setup does not. Reinstall the app, then set endpoints.agents.channels.nativeSessions: true in librechat.yaml. Without the required permissions or Stop subscription, the gateway falls back to durable progress controls. See Slack Agent sessions for app configuration.

Native sessions show processing or waiting-for-input status and return to active when the run finishes. Completed answers can include Helpful/Not helpful controls. Optional lifecycle reactions use endpoints.agents.channels.lifecycleReactions: true, are separate from native sessions and require the reaction permissions already listed in the basic bot scopes. Neither an acknowledgement nor a reaction proves a tool completed; Stop requests cancellation of the sender's authorized work, not another participant's run.

Kubernetes and Helm

The LibreChat Helm chart supports shared workspaces and manual connections. Both require a transaction-capable database; the default standalone database cannot run Channels. See Helm configuration for the application's environment, credentials and database setup.

Enabling the gateway requires an explicit image.tag selecting a published LibreChat release containing Channels; the chart refuses to silently use its older application-version default. The gateway image tag defaults to that same selected release. Earlier releases have no gateway image. A custom channelGateway.image.tag is available for deliberate image overrides.

Shared workspace deployment

Select a release containing organization workspaces and provide an existing Secret with CHANNEL_SERVICE_TOKEN. The service token is shared with LibreChat. No Slack app credentials belong in this Secret: organization admins register their apps in the UI after deployment. Existing explicit API environment entries take precedence over the generated service-token reference.

The example below selects a replica set for a fresh bundled MongoDB. For an existing standalone database, plan and complete its data migration before changing topology; a Helm value does not migrate existing data. For an external transaction-capable database, supply its connection through your normal application configuration and disable the unused bundled database with mongodb.enabled: false. Shared mode refuses to render when LibreChat would use a bundled standalone MongoDB; existing external connection overrides remain supported.

image:
  tag: <published-release-containing-organization-workspaces>
mongodb:
  architecture: replicaset
channelGateway:
  enabled: true
  mode: shared
  replicaCount: 2
  existingSecretName: gateway-service-credentials
  ingress:
    enabled: true
    host: slack.example.com
    tls:
      - hosts: [slack.example.com]
        secretName: slack-gateway-tls

Set public HTTPS DOMAIN_SERVER and DOMAIN_CLIENT through the application's normal environment settings. Shared mode supplies the app enablement flag and derives SLACK_GATEWAY_URL from its ingress host unless explicitly configured in librechat.configEnv. It omits connection IDs, tenant IDs and the Socket Mode token. Shared replicas use rolling updates and the existing durable claims; mode: single requires one replica and uses replacement updates. After deployment, organization admins register their apps and configure the displayed Slack URLs through Account settings, then use Agent Builder; no per-workspace Helm values or pods are required.

Manual connection deployment

First upgrade the application to a published release containing Channels with the gateway disabled. Configure the manual channel policy, then create and activate the connection in the Agent builder. Enable the gateway after obtaining its connection ID:

image:
  tag: <published-release-containing-channels>
channelGateway:
  enabled: true
  channelId: <connection-ID-from-Agent-builder>
  tenantId: "_"
  # Defaults to global.librechat.existingSecretName.
  existingSecretName: librechat-credentials-env

To set the name used in gateway messages, configure channelGateway.appTitle. It defaults to librechat.configEnv.APP_TITLE, then LibreChat. Set it explicitly if the API obtains APP_TITLE through a Secret or global.librechat.env.

The gateway title must:

  • Be nonempty after trimming.
  • Have at most 40 UTF-16 characters.
  • Contain no <, >, | or control characters.

If the application name does not fit, choose a shorter gateway title. Helm rejects incompatible inherited titles before deployment; the application can keep its existing longer name.

For manual Socket Mode, the existing Secret must contain CHANNEL_SERVICE_TOKEN matching LibreChat's server configuration and SLACK_APP_TOKEN for the matching app. By default, the application's existing Secret supplies the same service token to LibreChat. The gateway references only these individual keys, not all provider/database credentials. If you choose a separate gateway Secret, keep its service token identical to the API's. Rotate through your normal secret-management process and restart the API and gateway after rotation; changing an existing Secret does not automatically restart pods.

The gateway derives the API URL from the chart's internal Service and port. Override channelGateway.internalUrl for a deliberately different service boundary. Configure gateway resources and annotations through channelGateway. Pod identity, enableServiceLinks, DNS, host aliases, image pull secrets, node selectors, tolerations and affinity follow the chart's shared platform settings. The configured ServiceAccount is reused while the gateway keeps its Kubernetes API token automount disabled. Manual single mode installs one gateway with replacement updates, so an upgrade may briefly interrupt Slack connectivity; it does not create another channel or Slack app.

For webhook transport, set the server policy to webhook, configure its public HTTPS gateway URL and clear channelGateway.slackAppTokenKey. Enable the dedicated gateway Ingress using your installed ingress controller and a trusted TLS certificate:

channelGateway:
  slackAppTokenKey: ""
  ingress:
    enabled: true
    host: gateway.example.com
    # Empty inherits ingress.className; set this for a different controller.
    className: nginx
    annotations: {}
    tls:
      - hosts: [gateway.example.com]
        secretName: gateway-tls

Combine these settings with the enabled gateway and explicit application release above. Set the server's gatewayUrl to https://gateway.example.com, with no path prefix. The new Ingress routes only /slack/events and /slack/interactions to the gateway Service on port 8080; its health and metrics routes remain private. It can share the application's hostname: the more specific Slack paths route to the gateway while the existing application Ingress keeps its own backend. Gateway annotations are separate so application rewrite rules cannot silently change callback paths. The gateway Ingress requires Kubernetes 1.19+.

The chart does not install an ingress controller or issue a TLS certificate. Configure TLS through the example Secret, your normal certificate controller/annotations, or an existing HTTPS termination layer. Slack needs a publicly trusted HTTPS endpoint. If you manage a separate external Ingress or need a custom base-path rewrite, leave channelGateway.ingress.enabled: false and route the callback paths to the rendered gateway Service yourself; do not add them as paths on the main application Ingress, whose backend is LibreChat. Socket Mode needs no public ingress.

By default, the gateway runs without an automatically mounted Kubernetes API token, as a non-root user with a read-only filesystem and dropped capabilities. The chart's global pod/container security contexts are honored for platform-specific overrides. Gateway version labels follow its selected image tag. /livez drives liveness and /readyz drives readiness. Startup before the API or channel is available fails closed; Kubernetes retries the process, and it becomes ready after validating the shared app policy or its bound active connection and transport.

After the Helm upgrade, check the gateway Deployment, pod events, logs and readiness. Missing Secret keys block pod startup; incorrect credentials or channel bindings prevent readiness.

Once it is ready, connect the Slack app, assign an agent, and link your account. Send the bot a new request to test the complete setup.

Next steps

Connect a Slack app and assign an agent, then finish setup with a real Slack message. See the gateway reference for rich-message formatting, service routes and delivery recovery.

How is this guide?