Optional, off by default. Install the standard setup first, from Install on EKS or Install on GKE. The Slack app runs in your cluster, next to it.
People @mention the app in a channel (or message it directly, if you allow DMs) and an agent picks up the thread. Follow-ups in that thread go to the same agent, with its context, however long the gap; several people can talk in one thread at once. Every agent is on your relay under its own name, so the agents can see and message each other. Nothing about the agents runs between messages: a message wakes the thread's agent, it answers, and it goes idle.
How it works
| Piece | What it does |
|---|---|
| Router | Holds the Slack connection over Socket Mode (an outbound WebSocket; no public URL). Records every message in a ledger: which agent owns each thread, who has spoken in it, and an append-only audit log. It is the only component with Slack credentials. |
| Agent host | Runs one agent per Slack thread as headless Claude Code, with its own resumable session on a volume. It has no Slack credentials. |
| relaygate (optional) | Carries all of the agents' Relaycast traffic, checks every Slack post and knowledge-base write against your policy, and withholds answers its classifier refuses. With its proxy on, the agents need no workspace key; narrow Relaycast's network policy to the gate so they can't go around it (Proxy Relaycast and Sessions). |
One message, end to end:
Create the Slack app
You create the app in your own Slack workspace; its tokens never leave you.
- Open https://api.slack.com/apps → Create New App → From a manifest,
pick your workspace and paste the
manifest.
To give the app your own name, render it with
render-manifest.py
--name "Your App". - Basic Information → Display Information: upload the app icon. Slack manifests can't carry an icon.
- Basic Information → App-Level Tokens → Generate Token and
Scopes: name it
socket, scopeconnections:write. Leave Token rotation off; the router doesn't refresh app tokens. Copy thexapp-…token. - Install App → Install to Workspace; copy the Bot User OAuth
Token (
xoxb-…). - Invite the app to the channel it should answer in (
/invite @Your App) and note the channel ID (channel name → About,C…). Start with one channel.
Store the secrets
The chart only references Kubernetes Secrets by name. Create them from your secret store; never paste the values into a values file.
| Secret | Keys | Value |
|---|---|---|
slack-relay-slack | bot-token, app-token | The xoxb- and xapp- tokens from above |
slack-relay-anthropic | api-key | An Anthropic API key. Use a zero-data-retention key if threads may contain regulated data; the chart can't check this. |
slack-relay-relaycast | workspace-key | A Relaycast workspace key for the agents' workspace (not needed with relaygate) |
slack-relay-relaygate | enrollment-key, identity-secret | Only with relaygate: the bridge enrollment key, and a stable random secret agents recover their identity with after a restart |
Install
# slack-relay-values.yaml
image:
digest: sha256:<published digest>
relaycast:
baseUrl: http://relaycast:8787
secrets:
relaycastWorkspaceKey: { name: slack-relay-relaycast, key: workspace-key }
slackBotToken: { name: slack-relay-slack, key: bot-token }
slackAppToken: { name: slack-relay-slack, key: app-token }
anthropicApiKey: { name: slack-relay-anthropic, key: api-key }
slack:
allowedChannels: [C0123456789]The chart isn't in a published release yet, so install it from a checkout of the infra repository:
git clone --depth 1 https://github.com/AgentWorkforce/infra.git
helm upgrade --install slack-relay ./infra/charts/slack-relay -n agent-relay -f slack-relay-values.yamlOr, if you install the umbrella from the same checkout, set
components.slackRelay: true and put the same values under slack-relay:.
Done when: the router logs socket mode connected, the host logs
registered relay agent slack-agent-host, and an @mention in the allowed
channel gets an answer in its thread.
Governance with relaygate
Optional. Install relaygate with its Relaycast proxy on and Relaycast narrowed to the gate, then add to the Slack app's values:
relaygate:
url: http://agent-relay-relaygate:8080 # <release>-relaygate; this is the umbrella's
secrets:
relaygateEnrollmentKey: { name: slack-relay-relaygate, key: enrollment-key }
agentIdentitySecret: { name: slack-relay-relaygate, key: identity-secret }With relaygate.url set, relaycast.baseUrl and the workspace key are
unused: every agent (router, host, one per thread) registers through the gate,
and all Relaycast traffic goes through it with the agent's own rg_ token. No
pod holds a Relaycast credential. Every Slack post and knowledge-base write is
checked first; a denied answer is withheld and the thread is told, and a DM
reply the gate denies is dropped.
Two things must match the gate's policy:
- The routing channel belongs to the pit. The chart's default policy owns
relaycast:channel/slack, matching the defaultrelaycast.channel(slack). If your policy only grants a prefix such asrelaycast:channel/slack-(the double-pit example), setrelaycast.channelto match, e.g.slack-pit; otherwise the router can't create its channel. - The bridge key's
namePrefixisslack-. Agent names start withslack-, so a key with any other prefix can't register them.
What leaves your cluster
- Slack API calls, from the router only.
- Anthropic API calls, from the agents (and the optional orchestrator).
- With relaygate on, every Slack post is checked first and withheld if your policy refuses it; the thread is told. Agents reach Relaycast only through the gate.
Agents can read only their own working folder by default (no shell, no web). The ledger records every inbound message, routing decision and outbound post, for audit.
The full reference, including the optional knowledge-base tools and Slack ingest, is in docs/self-hosted-slack-relay.md.