Skip to main content
Early access. GitHub and Slack runs start in a cloud sandbox operated by Mutagent, and cloud sandboxes are not open to every account yet: we are letting accounts in gradually while we test. There is nothing to host, and nobody has to be at a terminal.
With the Mutagent Slack app in your workspace, a mention in a channel you choose starts a Helix run in a cloud sandbox, and the run replies in that message’s thread. Your team asks for an evaluation or a diagnosis in the channel where it already works, and reads the answer there.

​
Before you start

  • The mutagent CLI is installed, you are signed in, and a workspace is selected. See Sign in.
  • Cloud sandboxes are enabled for your account (early access).
  • GitHub is connected, because every run works on a repository. See GitHub.
  • A person who can add apps to your Slack workspace is at a browser. That step cannot be done from the CLI.

​
Connect

A person connects Slack once for the organization, in a browser. In the web app, go to Configuration › Integrations and click Connect on the Slack card. Or use the CLI:
The command prints two links and exits 0. Open the sign-in link (data.signInUrl) first and sign in to Mutagent, then open the second link (data.url) in the same browser to add the Mutagent Slack app to your Slack workspace. Then wait for it to finish:
<attempt-id> is data.attempt from the first command. Running connect again once Slack is connected does nothing and exits 0. The app asks Slack for four bot permissions: Invite the app to each channel you want it to answer in. Every run works on a GitHub repository, so connect GitHub too and give the Mutagent GitHub App access to the repositories your team will ask about. mutagent gateway status --json shows what is connected in data.connections and the next command to run in next. See Connecting GitHub and Slack for the full flow and what to do when a step fails.

​
Start runs from a channel

A Slack trigger names the channel it listens in and the instruction Helix receives with each mention. When someone mentions the app there, the gateway starts a run with that instruction and the message text, and posts the result as a reply in the thread. Replying in the same thread continues the conversation with the run. Replies are redacted before they are posted: the gateway strips values that look like keys or tokens.

​
Which repository a mention runs on

There is no default repository. A mention can run on any repository the Mutagent GitHub App can reach, except one you unlinked from the workspace with mutagent gateway repos unlink. For a mention answered by the built-in trigger, the app picks the repository in this order:
  1. The repository the message names: owner/name, a GitHub URL, or a repository name only one of those repositories has.
  2. The repository this thread already runs on.
  3. The only repository, when the app can reach exactly one.
Otherwise the app asks in the thread: “Which repository should I run this on? Pick one below, or mention me again and name it (owner/name).” It offers the repositories the app can reach, one button each, and the run starts on the one you click. The app shows at most 10 buttons. With more repositories than that, name the one you want. The repository a mention runs on is linked to your workspace automatically. When the app can reach no repository at all, it replies “No repository is available here, so nothing was run. Give the Mutagent GitHub App access to a repository on GitHub, then mention me again.” To change which repositories the app can reach, change its access on GitHub (mutagent gateway repos grant-more prints the page). A trigger you create for a channel always runs on the repository you gave it with --repo.

​
One thread, one session

Each thread holds one session.
  • While the session is running, a reply in the thread goes to that session. Mentioning the app again in the same thread also goes to that session; it does not start a second run.
  • A session lasts up to 60 minutes from the mention. When that time is up, the app posts any answers not yet posted and then “This session ended after 1 hour. Mention me in a new message to start a new session.”
  • A session stops sooner after 15 minutes with no activity. The app posts nothing then. The next reply in the thread gets “This session ended. Mention me in a new message to start a new session.”
  • After the session ends, the thread starts nothing new. A mention there gets that same line once. To start again, mention the app in a new message, outside the thread. The new session starts fresh, without the old thread’s conversation.
  • If the app cannot tell whether a reply reached the session, the thread pauses rather than risk sending it twice. A mention or reply there gets “This thread is paused. Mention me in a new message to start a new session.”
Without a trigger of your own, the app still answers mentions: a built-in trigger does, in every channel it is in. A trigger you create answers in the channels you name with --channel, which is required for slack.mention. It takes Slack channel IDs (such as C0123456789), not channel names. A channel that another enabled trigger already holds is refused with TRIGGER_CONFLICT:
See Triggers and routines for every option. When a mention starts no run, the reason is recorded. mutagent gateway notices list --json lists each one with its code, its reason and the fix as a command.

​
Report a problem instead of starting a run

Start the message with triage or report right after the mention, for example @Mutagent report the refund bot quoted the wrong policy. The app files it as an item to review instead of starting a run, and replies in the thread with a link to review it in the web app. To file it under one agent, name it before a colon: @Mutagent triage support-bot: it loops on refunds.

​
Nothing to host

There is no bot token to create and no listener to run yourself. The Slack app, the event delivery and the runs are operated by Mutagent; you authorize the app once with mutagent gateway connect slack.