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

# Install Helix

> One command installs Helix, the `helix` binary. No Node, no npm, no checkout.

Helix ships as one binary. It includes the agent runtime, sub-agents (helper agents it starts for
parallel work) and the trace viewer, and needs no Node, npm or source checkout.

## Before you start

* macOS (Apple Silicon or Intel) or Linux (arm64 or x64), with `curl` and `bash`.
* An API key or subscription for an LLM provider, such as Anthropic, OpenAI or Google. Helix calls
  the model with your credentials.
* No Mutagent account is needed to install or run Helix on your machine.

<Note>
  **For coding agents:** installing writes a binary to the user's machine. Confirm with the user
  first, and do not edit their shell startup files yourself.
</Note>

<Steps>
  <Step title="Install">
    One command:

    ```bash theme={null}
    curl -fsSL https://install.mutagent.io/helix | bash
    ```

    Gives you the `helix` command. It's proprietary, and it runs on macOS (Apple Silicon or Intel)
    and Linux (arm64 or x64).

    If you use the [`mutagent` CLI](/cli/overview), `mutagent install helix` installs the same binary.

    <Tip>
      Don't pipe a script you haven't read straight into a shell. Download it first, look at it,
      then run it:

      ```bash theme={null}
      curl -fsSL https://install.mutagent.io/helix -o helix.sh   # read it, then:
      bash helix.sh
      ```
    </Tip>

    <Note>
      The installer also keeps a `mutagent-helix` link to the same binary, so scripts that used the
      older name keep working.
    </Note>
  </Step>

  <Step title="Where the binary goes">
    The installer puts the binary at `~/.mutagent/bin/helix` and links it as `~/.local/bin/helix`,
    creating that folder if needed. When only `~/bin` is on your `PATH`, it links it there instead.
    If the link folder is on your `PATH`, `helix` works in the same terminal.

    The installer never edits your shell profile. If the folder is not on your `PATH`, it prints the
    line to add yourself, and the full path that always works: `~/.mutagent/bin/helix`.

    `mutagent install helix` installs the same binary. With `--json`, read `binaryPath`, `version`
    and `onPath`.
  </Step>

  <Step title="Verify">
    `--strict` is the real check: it also starts the built-in agent runtime and fails if that
    doesn't work. (The installer already checked the download against its published checksum.)

    ```bash theme={null}
    helix --version
    helix doctor --strict
    ```

    `helix --version` prints the Helix version and the version of the built-in agent runtime.
    `helix doctor --strict` exits 0 when the install works.

    To check that a provider works, run `helix --list-models` after the next step: it lists the
    models your key can use. `helix smoke` checks that everything bundled inside the binary is present. It doesn't
    use the network.
  </Step>

  <Step title="Sign in to a provider">
    The model catalog ships inside the binary, but a model only appears once its provider has
    credentials. A launch with no provider still renders the dashboard, then warns:
    **"No models available. Use /login to sign in to a provider with OAuth or an API key."** — that
    is a missing key, not a broken install. (Headless runs exit instead, with
    *"No API key found for \<provider>."* followed by the same hint.)

    Either sign in from inside the session — `/login` to set up your provider or subscription, then
    `/model` to pick a model — or export a key before launching:

    ```bash theme={null}
    export ANTHROPIC_API_KEY=…     # or OPENAI_API_KEY, GEMINI_API_KEY, …
    ```

    AWS Bedrock and Google Vertex credential chains are honoured too. Helix talks to the provider
    with your credentials; there is no Mutagent inference bill.
  </Step>

  <Step title="Launch">
    Run it in your project directory. You land on the Helix dashboard: the five stages of the
    agentic development lifecycle (ADLC), the skills (packaged instructions Helix loaded for each
    stage), and the list of slash commands. Drive it in plain English from there.

    ```bash theme={null}
    cd your-project
    helix
    ```

    That is one of three ways to run it. `helix agent` (agent mode) gives you a plain coding agent
    without the five stages, and `helix --prime` the experimental Prime mode, where the model works
    by writing and running code. See
    [Three ways to run Helix](/helix/modes).
  </Step>
</Steps>

## If it fails

| Symptom | Fix |
| - | - |
| `helix: command not found` | Your shell does not look in `~/.local/bin`. The installer says so and prints `Launch ~/.mutagent/bin/helix`: run Helix by that full path. It also prints a one-line command for adding `~/.local/bin` to your PATH if you want that; it never changes your shell files. |
| An old `# helix (added by installer)` line in your shell startup file | Older installers appended it. The current installer and uninstaller never edit shell files, so delete that line by hand if you no longer want it. |
| `helix doctor --strict` exits non-zero | Re-extract the bundled runtime: `helix doctor --refresh-runtime`, then run `helix doctor --strict` again. If it still fails, run the installer again. |
| "No models available" or "No API key found for \<provider>" | No provider credentials. Export a key such as `ANTHROPIC_API_KEY`, or run `/login` inside Helix. |
| `helix auth`, `helix config` or `helix install` exits with code 2 | These are not Helix commands. Helix prints one line to stderr and exits 2. Set up providers with `/login` or an exported key. |
| You need diagnostics while Helix starts | Add `--warn` (or set `MUTAGENT_HELIX_WARN=1`). |

## Update

```bash theme={null}
helix update            # fetch and install the current build, verifying its checksum
helix update --check    # report only: exit 1 when a different build is published, 0 when current
```

Re-running the installer command also works and does the same thing.

To try a release before it becomes the default, use the preview channel:
`helix update --channel candidate` (or `mutagent install helix --channel candidate`).

## Remove it

```bash theme={null}
curl -fsSL https://install.mutagent.io/helix | bash -s -- uninstall
```

Add `--purge` to also drop the cached runtime.

<Card title="Next: three ways to run Helix" icon="arrow-right" href="/helix/modes">
  The full Helix session, agent mode, or the experimental Prime mode: what each gives you and what to type.
</Card>


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