Skip to main content
You will install the helix binary, give it a model, optionally sign in with the mutagent CLI, and run a first turn of the agentic development lifecycle (ADLC) on your machine. Before you start
  • macOS (Apple Silicon or Intel) or Linux (arm64 or x64), with curl.
  • An API key for one model provider (Anthropic, OpenAI, Google, Z.AI and others).
  • For the mutagent CLI step: Node.js 22.18 or later (or Bun 1.1 or later), and a Mutagent account or an API key from one (you can create the account during sign-in).
Following this as a coding agent? Every step below has a non-interactive form. Run commands in one shell session so export lines carry over, and pass --json to mutagent commands.
1

Install Helix

The installer downloads the binary for your platform, checks it against the published checksums, puts it at ~/.mutagent/bin/helix, and links it as ~/.local/bin/helix (or ~/bin when only that is on your PATH). It never edits your shell profile. If the link folder is not on your PATH, it prints the line to add yourself; until then, run ~/.mutagent/bin/helix.
Output
The first line is the Helix version you installed. The second line is the version of the agent runtime Helix is built on, and your platform; you can ignore it.Already use the mutagent CLI? mutagent install helix installs the same binary. Install Helix covers the install options, updates and removal.
2

Give Helix a model

Helix calls the model provider directly with your credentials. Export a key before launching:
Or start helix and type /login to sign in to a provider or subscription, then /model to pick a model. Without a provider, Helix starts and warns “No models available. Use /login to sign in to a provider with OAuth or an API key.”Check that a provider works, without opening the interactive screen:
It lists the models your key can use when a provider works. If it prints “No models available…” instead, Helix has no model: export the key in the same shell that runs helix.
3

Sign in to Mutagent (optional for local use)

Helix itself does not need this sign-in to run locally. You need it for the hosted parts: workspaces, stored LLM providers, Environments and the SDK. Skip to the next step if you only want Helix on this machine.The mutagent CLI connects this machine to your Mutagent account: your workspaces, the LLM providers stored in them, and Environments (named sets of variables and secrets for cloud runs). Install it with npm, bun or pnpm:
In a terminal, mutagent login asks whether to sign in with the browser or an API key. The browser path opens app.mutagent.io, where you sign in or create an account and approve the CLI. The CLI waits up to 5 minutes, then stores a key that works in every workspace you belong to in that organization, for 30 days.Without a terminal prompt (a coding agent, CI or a script), use one of these:
The browser form never opens a browser itself under --json: it prints the sign-in URL and waits up to 5 minutes. Give that URL to the person, who signs in and approves the CLI. Keys come from API keys.Check the sign-in, then the workspace:
mutagent auth status proves the sign-in: exit 0 means the key is valid, 2 means it expired or is invalid (sign in again), 3 means you are not signed in. Its last line may be ⚠ Onboarding: Not initialized (run mutagent init); that is expected, and Helix does not need mutagent init.mutagent workspaces current --json proves a workspace is selected: exit 0 prints a workspace object; exit 3 means you are not signed in or no workspace is selected (run mutagent workspaces list --json, then mutagent workspaces use <name>). See Accounts, organizations and workspaces.
4

Ask Helix one question

helix -p "<prompt>" sends one prompt, prints the answer and exits, without opening the interactive screen. Run it in any project directory:
Output
The command exits when the answer is printed. If it fails with no answer, run helix --list-models from step 2.Those five stages are what Helix does for an agent: write down what it should do (spec), build it, score it on real runs (evaluate), find out why it fails and propose fixes (diagnose), and apply the fixes you approve, re-evaluating until your criteria pass (optimize). Each one starts with the command shown.
5

Start with a spec

Run helix with no arguments to open the interactive session, then describe the agent you want to build:
Helix reads your project for context, then interviews you with structured questions (output format, what to do when a clause is missing, where the agent will run). It ends with a validated agentspec.yaml and names the next step:
The interview needs someone to answer its questions on the interactive screen. Without one (helix -p), Helix cannot show the questions, so put the answers in the prompt, and send follow-ups to the same session with -c (continue the previous session):
Your first loop follows this agent through build and evaluate, with the real session output at each step.

​
Already have an agent?

You do not have to start at Spec. Point Helix at an agent that already runs and has traces:
Helix reads the traces from your machine (Claude Code, Codex and Helix sessions, JSONL files, OTLP/JSON files) or from Langfuse. See Supported integrations for the full list.

Your first loop

One agent taken from a sentence to a spec, a build and a verdict.

API keys

Sign in without a browser, for CI and scripts.