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

# mutagent install

> Install the Helix binary on your machine.

Install the `helix` binary on this machine. It is the same binary the install script at
`install.mutagent.io` installs. To run Helix in a cloud sandbox instead, use
[mutagent helix](/cli/commands/helix).

**Before you start:** [install the CLI](/cli/installation). You do not need to be signed in. The
command writes a binary to this machine, so a coding agent should confirm with the person first.

## mutagent install helix

```bash theme={null}
mutagent install helix --json
mutagent install helix --channel candidate --json
```

| Flag | What it does |
| - | - |
| `--channel <latest\|candidate>` | The release channel to install from. The default is `latest`. `candidate` installs the next release before it is promoted to `latest`. |

What it does:

1. Downloads the `helix` binary for your system: macOS or Linux, on x64 or arm64.
2. Checks it against the published checksums, and stops if they do not match.
3. Writes it to `~/.mutagent/bin/helix`, with a `mutagent-helix` alias to the same binary.
4. Runs `helix --version` to confirm it starts.

It never edits your shell startup files. If `~/.mutagent/bin` is not on your `PATH`, it prints the
line to add. You do not need to be signed in.

| Environment variable | What it does |
| - | - |
| `MUTAGENT_HELIX_CHANNEL` | `latest` or `candidate`. `--channel` wins over it. |
| `MUTAGENT_INSTALL_DIR` | Install into this folder instead of `~/.mutagent/bin`. |

### Check the result

Exit code `0` means Helix is installed and `helix --version` ran. With `--json`, read these fields:

| Field | What it holds |
| - | - |
| `success` | `true` |
| `version`, `channel` | The installed Helix version and the channel it came from. |
| `binaryPath` | Where the binary was written, for example `~/.mutagent/bin/helix`. |
| `onPath` | `false` when the install folder is not on your `PATH`. |
| `pathLine` | Present when `onPath` is `false`: the line to add to your shell profile. Show it to the person; do not edit their shell files for them. |
| `telemetry` | `sent`, `skipped` (not signed in) or `failed`. It never changes the result. |

If `onPath` is `false`, run Helix by its full path (`~/.mutagent/bin/helix`) until the person adds
`pathLine` to their shell profile.

### If it fails

The command exits `1` and prints the error code and a fix. See [CLI errors](/cli/errors).

| Error code | Fix |
| - | - |
| `INSTALL_UNSUPPORTED_PLATFORM` | Helix builds exist for macOS and Linux on x64 and arm64. On Windows, run the command inside WSL. |
| `INSTALL_DOWNLOAD_FAILED` | Check the network connection and the channel name, then run the command again. |
| `INTEGRITY_ERROR` | The download failed the checksum check. Nothing was installed. Run the command again. |
| `INSTALL_ASSET_MISSING` | The channel has no build for this machine. Try the other channel (`--channel latest` or `--channel candidate`). |
| `INSTALL_WRITE_FAILED` | The install folder is not writable. Set `MUTAGENT_INSTALL_DIR` to a writable folder and run again. |
| `INSTALL_VERIFY_FAILED` | The binary was written but `helix --version` failed. Run `~/.mutagent/bin/helix doctor`, then run the install again. |
| `INVALID_ARGUMENTS` | The package is not `helix`, or the channel is not `latest` or `candidate`. |

Then run `helix` in your project. [Install Helix](/helix/install/standalone) covers LLM-provider
sign-in, updates and removal.


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