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

> Run Helix in a cloud sandbox: the orchestrator, Prime, or your own agent, on a task or as a live session.

<Note>
  **Early access.** Cloud sessions and managed agent runs are not open to every account yet: we are
  letting accounts in gradually while we test. They run in a cloud sandbox operated by Mutagent, so
  there is nothing to host. A sandbox with nothing to do for 15 minutes stops; send the session a
  message and it wakes up, delivers your message and carries on in the same conversation.
</Note>

`mutagent helix` runs Helix in a cloud sandbox instead of on your machine. Choose what runs with the
command and how it runs with a mode flag: `-p`, `--mode json`, or `--mode rpc`. A managed agent run
may omit the mode flag; the mode set in its `agent.md` then applies. There is no terminal chat client.

To install Helix on your machine instead, use [mutagent install](/cli/commands/install).

## Before you start

1. [Install the CLI](/cli/installation) and [sign in](/cli/commands/login). A coding agent signs in
   with `MUTAGENT_API_KEY=<key> mutagent login --json`, or runs `mutagent login --browser --json`
   and shows the printed URL to the person.
2. Select a workspace: `mutagent workspaces use <workspace-name>`, or pass `--workspace <name>`
   before `helix` for one command.
3. Give the workspace a model. `mutagent helix models --json` must list at least one model and a
   default, or you pass `--model <provider/model>`. See [mutagent helix models](/cli/commands/helix-models).
4. Optional: create an [Environment](/cli/commands/env) if the task needs variables or secrets, and
   connect GitHub with [mutagent gateway](/cli/commands/gateway) to use `--repository`.

Choose the mode yourself on every run: `-p`, `--mode json` or `--mode rpc`. The global `--json` flag
does not apply to a run; its output is Helix's own.

## mutagent helix

Run the Helix orchestrator, with its lifecycle stages and sub-agents.

```bash theme={null}
mutagent helix -p "Plan an evaluation for a support-triage agent."
```

Takes the [mode flags](#mode-flags), [placement and model flags](#placement-and-model-flags), and
[Helix flags](#helix-flags).

## mutagent helix --prime

Run the Prime agent.

```bash theme={null}
mutagent helix --prime --mode rpc
```

Takes the same flags as `mutagent helix`.

## mutagent helix agent

Run your own agent definition instead of the orchestrator. The first argument is the definition, not
the task.

```bash theme={null}
mutagent helix agent "You write release notes." -p "Write release notes for version 1.2."
```

| Flag | What it does |
| - | - |
| `<definition>` (first argument) | The agent definition as text. |
| `--prompt <text>` | The agent definition as text. Same as the first argument. |
| `--file <path>` | Read the agent definition from a file on your machine and send its contents. |
| `--name <name>` | Use a named agent from your local agent directories, or else one built into the cloud sandbox. |
| `--prime` | Run the definition as the Prime agent. |
| `@<slug>` (first argument) | Run the [managed agent](/helix/cloud/managed-agents) with this slug: the slot's active revision. |
| `@<slug>:v<N>` | Run revision N of the managed agent. |
| `@<slug>:latest` | Run the managed agent's newest validated revision, active or not. |
| `--env <name>` | With `@<slug>`, use the slot in this Environment and load the Environment into the sandbox. Without it, the default slot is used. |

With no definition, a general-purpose agent runs. Also takes the [mode flags](#mode-flags),
[placement and model flags](#placement-and-model-flags), and [Helix flags](#helix-flags).

A managed agent runs with `-p "<task>"` or `--rpc`. With neither flag, it uses the mode set in its
`agent.md`. Check, deploy, activate, and retire managed agents with [mutagent agent](/cli/commands/agent).

```bash theme={null}
mutagent helix agent @invoice-pricing --env prod -p "Price three widget units."
mutagent helix agent @invoice-pricing:v2 --env prod --rpc
```

The managed agent's package sets its prompt, tools, skills and model, so other Helix flags and
`--cwd` are refused. Before any output, the run prints a receipt on stderr as one JSON line: the
session reference, the sandbox, the agent and the mode. With `-p`, the session takes no more input
after the task, so `session send` is refused.

## Mode flags

| Flag | What it does |
| - | - |
| `-p <task>` | Run the task to completion and print the final answer on stdout. |
| `--mode json` | Print one JSON event per line on stdout. Pass the task as a message after the flag, or with `-p`. |
| `--mode rpc` | Start a live session that reads JSON commands from stdin. |
| `--rpc` | Same as `--mode rpc`. Cannot be combined with `--mode json`. |

Every run prints its session reference, which starts with `hs1_`, on stderr. Use it with
[mutagent helix session](/cli/commands/helix-session). The CLI exits with Helix's exit status.

Ctrl-C sends `SIGINT` to the session, which stops it. With `--mode rpc`, closing stdin ends the
session's input; a dropped connection only detaches, and the session keeps running. `--json` does
not change a run's output: it is Helix's own.

```bash theme={null}
mutagent helix agent "You explain concepts in one sentence." --mode json "Explain a closure."
```

## Placement and model flags

| Flag | What it does |
| - | - |
| `--model <provider/model>` | Use this model. It must be listed by [mutagent helix models](/cli/commands/helix-models). Without it, the workspace default is used. A managed agent uses the model its package declares. |
| `--env <name>` | Load this [Environment](/cli/commands/env) into the sandbox. |
| `--sandbox-provider <name>` | Run on this sandbox provider instead of the default. An unknown name is refused with the list of valid names. |
| `--preset <name>` | Start the sandbox from this preset instead of the default. [mutagent sandbox presets](/cli/commands/sandbox#mutagent-sandbox-presets) lists the names. An unknown name is refused. |
| `--cwd <path>` | Working directory inside the sandbox. |
| `--repository <owner/name>` | Start in a checkout of this GitHub repository. The workspace must have a GitHub connection that can reach it. The checkout is the working directory, so `--cwd` is refused with it. A managed agent (`@<slug>`) refuses it. |
| `--branch <name>` | The branch of `--repository` to check out. The default is the repository's default branch. Needs `--repository`. |

A sandbox idle for 15 minutes is stopped. An interactive session in it is checkpointed first, and a
later `session send` wakes it in a new sandbox from that checkpoint.

```bash theme={null}
mutagent helix agent --file ./agents/reviewer.md --model <provider/model> --env ci -p "Review the open changes."
```

```bash theme={null}
mutagent helix --repository <owner/name> --branch <branch> -p "Run the tests and summarize failures."
```

## Helix flags

These flags work as they do in local Helix.

| Flag | What it does |
| - | - |
| `--thinking <level>` | Set the model's reasoning level. |
| `--tools <list>`, `--exclude-tools <list>`, `--no-tools` | Choose which tools the agent can use. |
| `--system-prompt <text-or-file>`, `--append-system-prompt <text-or-file>` | Replace or extend the system prompt. When the value is a file on your machine, its contents are sent. |

These are refused because they point at files or state that only exist on your machine:
`--extension`, `--skill`, `--session`, `--continue`, `--resume`, and `@file` arguments. Model API keys
on the command line are refused too; they come from [LLM providers](/cli/commands/providers).

## Check the result

* The session reference (`hs1_…`) is on stderr as soon as the run starts. Keep it: `session attach`,
  `send`, `signal` and `checkpoint` take it. A managed agent run prints it in the JSON receipt line.
* With `-p`, stdout holds the final answer. With `--mode json`, stdout holds one JSON event per line.
* The exit code is Helix's own: `0` means Helix ended normally. In `--mode json`, also check for an
  assistant message with `stopReason: "error"`; a failed model call can still exit `0`. See
  [Exit status](/helix/cloud/agent-runs#exit-status).

## If it fails

A refusal before the session starts uses the CLI's exit codes. With `-p` it is text on stderr. With
`--mode json` or `--mode rpc` it is one JSON line on stderr:
`{"success":false,"code":…,"error":…,"suggestedAction":…,"_agentGuidance":{"fix":[…],"notes":[…],"escalate":…}}`.
stdout stays empty. Run the commands in `fix`, follow `notes`, and hand `escalate` to the person.

| Exit code or error | Fix |
| - | - |
| `3` (`AUTH_REQUIRED`, `WORKSPACE_REQUIRED`) | [Sign in](/cli/commands/login), then `mutagent workspaces use <workspace-name>`. |
| `2` (`AUTH_EXPIRED`, `INVALID_API_KEY`) | Sign in again, or set a valid `MUTAGENT_API_KEY`. |
| `CLOUD_NOT_ENABLED` (exit 1) | Cloud sandboxes are not enabled for your account yet. Nothing was started. |
| HTTP 428 `NO_PROVIDER_CONFIGURED` (exit 1) | Read the message. No default model: pass `--model <provider/model>` or run `mutagent helix models default <provider/model>` (any workspace member can). Provider not configured: `mutagent providers add --provider <type> --name <name> --api-key-stdin` or `mutagent providers mirror`, after confirming with the user. See [troubleshooting](/helix/cloud/troubleshooting). |
| HTTP 422 for the model (exit 1) | The `--model` value is not in `mutagent helix models`. Copy the ID exactly. |
| `github_not_connected`, `repository_inaccessible`, `BRANCH_NOT_FOUND` (exit 1) | `--repository` could not be checked out. Follow `_agentGuidance`: connect GitHub with `mutagent gateway connect github --wait`, grant access with `mutagent gateway repos grant-more`, or fix the branch name. |
| A flag or local file is refused (exit 1) | The sandbox does not have your files. See [Helix flags](#helix-flags). |

If a run fails after it printed a session reference, the session may still be running. Check
`mutagent helix session list --json` before you start the task again. More cases:
[Troubleshooting cloud runs](/helix/cloud/troubleshooting) and [CLI errors](/cli/errors).


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