mutagent install

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. Before you start: install the CLI. 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

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:

Downloads the helix binary for your system: macOS or Linux, on x64 or arm64.
Checks it against the published checksums, and stops if they do not match.
Writes it to ~/.mutagent/bin/helix, with a mutagent-helix alias to the same binary.
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.

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 covers LLM-provider sign-in, updates and removal.

CLI

Account

Workspace

Helix

Setup