> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mutagent.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Gateway overview

> The gateway starts Helix runs from events and schedules: a GitHub mention, an opened issue, a Slack message, a webhook, or a time of day.

<Note>
  **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.
</Note>

The gateway watches GitHub, Slack and your own webhooks, and starts a Helix run when something you
named happens. The run works in a cloud sandbox, usually on one of your repositories, the same way
[`mutagent helix`](/cli/commands/helix) does, except nobody has to be at a terminal to start it.

Everything the gateway does is workspace configuration. It belongs to one workspace, it is stored in
the cloud, and every command below acts on the workspace
[your CLI is set to](/cli/commands/login#mutagent-workspaces-use).

## The five things you work with

| Name | What it is |
| - | - |
| **Connections** | GitHub and Slack, each connected once for your organization. |
| **Repositories** | The repos you give the Mutagent GitHub App access to on GitHub. Each is linked to the workspace the first time you use it. |
| **Triggers** | An event kind plus an instruction: when this happens, run this. |
| **Routines** | A schedule plus an instruction: at these times, run this. |
| **Runs** | One history for everything that started an agent: triggers, routines, test runs and `emit` (a run you start by sending a named event with `mutagent gateway emit <kind>`). |

## What a trigger is

A trigger pairs three things: an **event kind** (what to listen for), a **repository** (where the run
works, chosen when you create the trigger), and an **instruction** (what Helix should do). When an
event of that kind arrives and matches the trigger, the gateway starts a run in a sandbox on the
repository's latest default-branch commit, pinned for that run.

There is no default repository. Name it with `--repo owner/name`: any repository the Mutagent GitHub
App can reach works, and it is linked to the workspace for you. Or run the command inside a clone
whose GitHub remote the app can reach, linked or not: the CLI uses that repository and tells you so.
A `webhook`, `emit:<kind>` or `trace.threshold` trigger (fires when the workspace records a set number of traces
within a time window) can take `--no-repo` instead, for runs that need no code. With no repository
chosen, the command is refused with `REPOSITORY_REQUIRED`.

The instruction is plain language — the same thing you would type after `helix -p`:

```bash theme={null}
mutagent gateway triggers create \
  --on github.issue.opened \
  --repo owner/name \
  --instruction "Triage: label, estimate, ask one clarifying question if needed"
```

A trigger runs as the person who created it, and only while they are still a member of the workspace.
If they leave, its runs stop with `RUN_PRINCIPAL_UNAVAILABLE` rather than running as someone else.

<Note>
  Mentions work before you create anything. A connected workspace already answers `@` mentions of
  the app on GitHub and in Slack. Those built-in triggers are listed alongside yours and are always
  on. See [Triggers and routines](/helix/gateway/triggers-and-routines#built-in-mention-triggers).
</Note>

## Start here

<Steps>
  <Step title="Connect GitHub">
    ```bash theme={null}
    mutagent gateway connect github
    ```

    Installing the GitHub App is a separate step from signing in with GitHub. You can also connect
    in the web app, under **Configuration › Integrations**. See
    [Connecting GitHub and Slack](/helix/gateway/connect).
  </Step>

  <Step title="Check which repositories the app can reach">
    ```bash theme={null}
    mutagent gateway repos
    ```

    These are the repositories you gave the app access to on GitHub. To add one, change the app's
    access there; `mutagent gateway repos grant-more` prints the page.
  </Step>

  <Step title="Prove it end to end">
    ```bash theme={null}
    mutagent gateway test-run --repo owner/name --wait
    ```

    This starts a real run and waits for it to finish.
  </Step>
</Steps>

At any point, run `mutagent gateway` with no arguments. It prints what is connected, what is missing,
and the exact next command to run.

```bash theme={null}
mutagent gateway
```

## For scripts and agents

Every gateway command takes `--json`. A success prints:

```json theme={null}
{ "success": true, "ok": true, "data": {}, "next": "mutagent gateway …" }
```

A failure prints:

```json theme={null}
{
  "success": false,
  "ok": false,
  "code": "REPOSITORY_REQUIRED",
  "error": "…",
  "suggestedAction": "…",
  "_agentGuidance": { "fix": ["mutagent …"], "notes": ["…"], "escalate": "…" }
}
```

* `next` (on a success) is the command to run next.
* `code` is the error code, upper case, exactly as the CLI prints it. Branch on it.
* `_agentGuidance.fix` holds commands that run verbatim (replace any `<placeholder>` first).
* `_agentGuidance.notes` is prose to read, not run.
* `_agentGuidance.escalate`, when present, means a person must act: stop and tell them.

Gateway commands use the CLI's exit codes:

| Exit code | Meaning |
| - | - |
| `0` | Success. |
| `1` | Failure, usage errors included. Read `code` and `_agentGuidance`. |
| `2` | Your Mutagent API key expired or is invalid. Sign in again. |
| `3` | Not signed in, or no workspace selected. |

There is no other exit code. See [Errors and exit codes](/cli/errors).

Destructive commands (`disconnect`, `repos unlink`, `triggers delete`, `routines delete`,
`runs cancel`) require `-f, --force`, with `--yes` as another name for it. The CLI never asks for
confirmation. See [mutagent gateway](/cli/commands/gateway).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.