Slack

The Slack app turns each thread into a session on your Pistis server. Mention the bot to start, reply in the thread to continue, and approve risky steps with buttons. The session is yours in the web app too, tagged Slack, with your agents, repositories and role.

Try it without SlackCopy Anchor Link

$ pnpm install
$ pnpm --filter @pistishq/slack-bot demo
BOT REPLIED: ▸ bash: {"command":"echo hello from your sandbox; uname -s"} | ✓ bash: hello from your sandbox | Linux | …

The demo starts a Pistis server, the Slack app and a local stand-in for Slack, mentions the bot and prints its reply.

Connect your workspaceCopy Anchor Link

1. Create a Slack app. Turn on Socket Mode and create an app-level token with connections:write. It starts with xapp-.
2. Add a bot token with app_mentions:read, chat:write, channels:history, users:read, users:read.email and commands. Add groups:history for private channels. It starts with xoxb-.
3. Subscribe to the app_mention and message.channels events. Add message.groups for private channels.
4. Turn on Interactivity for the buttons, and add the slash command /pistis.
5. Connect Slack to your server: add "slack": { "botToken": "${SLACK_BOT_TOKEN}" } to pistis.json and restart it.
6. Issue the app's key on the server's host. Pistis keeps only its hash:

$ pistis admin slack key --config pistis.json
slack app key (shown once): psk_…

1. Start the app anywhere it can reach your server and Slack. It opens no port:

PISTIS_URL=https://pistis.example.com PISTIS_SLACK_KEY=psk_… \
  SLACK_APP_TOKEN=xapp-… SLACK_BOT_TOKEN=xoxb-… \
  npx @pistishq/cli slack

From a clone of the repository, run pnpm --filter @pistishq/slack-bot start with the same variables instead. To build your own bot on it, npm i @pistishq/sdk and call createSlackSurface({ server, appToken, botToken }) from @pistishq/sdk/slack; recipes/slack-bot has an example and an app manifest.

Run it next to your serverCopy Anchor Link

The product image includes the app. With Docker Compose, add a service next to the Pistis servers:

  slack:
    image: pistis/pistis:dev
    restart: unless-stopped
    command: ["slack"]
    environment:
      PISTIS_URL: http://brain1:8787
      PISTIS_SLACK_KEY: ${PISTIS_SLACK_KEY}
      SLACK_APP_TOKEN: ${SLACK_APP_TOKEN}
      SLACK_BOT_TOKEN: ${SLACK_BOT_TOKEN}

The image's entrypoint is the pistis command, so this runs pistis slack. On Kubernetes, run one replica of the same image with that command and PISTIS_URL=http://<release>-pistis, its three values from a Secret. Give the Pistis servers SLACK_BOT_TOKEN with envFrom and config.slack.botToken. Run pistis admin slack key in a server pod. The app keeps nothing, so it can restart at any time; threads continue.

Link peopleCopy Anchor Link

Most people are linked the first time they use the bot: if Slack's verified email for them is the email of exactly one person in Pistis, they are linked at once. Anyone else types /pistis link in Slack. The bot sends them a link that works once, for an hour; they open it while signed in to Pistis and click Link. Their Account page says whether Slack is linked. Every link is in the audit log.

From the shell, an admin can link someone directly: pistis admin slack link --config pistis.json --slack T0123:U0456 --user ann@example.com.

In a threadCopy Anchor Link

• Mention the bot to start a session as you. The thread is its record; its link opens it in the web app.
• Reply to continue. A reply while the agent works steers it; a reply while it asks you a question answers it.
• Command words at the start of a reply: stop stops the agent; plan followed by a message asks for a plan without changing anything, which the thread shows as numbered steps; model lists the models and model followed by one switches the session to it. Each is done as you, with your role and what the session's owner shared with you.
• Approve or Deny with the buttons. Pistis checks each click: the session's owner and people it's shared with as approver can decide; anyone else is told they're not allowed.

Others in the thread act as themselves: someone the session isn't shared with can't change it. A flow the agent proposes appears in words with Dismiss; save it on the session's page.

SettingsCopy Anchor Link

Models, approvals, sandboxes and MCP servers are your server's settings.