> ## 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`. |

## 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 of
a linked repository and the CLI uses that one and tells you so. A `webhook`, `emit:<kind>` or
`trace.threshold` trigger 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` and answers with one envelope:

```json theme={null}
{ "ok": true, "data": {}, "next": "", "error": { "code": "", "reason": "", "fix": [], "notes": "" } }
```

`next` names the command to run after a success. On a failure, `error.fix` holds commands that run
verbatim, and `error.notes` is prose to read rather than run. A failure that no command can resolve
has an empty `fix` and explains itself in `notes`.

| Exit code | Meaning |
| - | - |
| `0` | Success. |
| `1` | Unexpected failure. |
| `2` | Needs a person or a browser. |
| `3` | Fixable configuration. |
| `4` | Refused. |

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.