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

# Run a task

> Give Helix a task in a cloud sandbox and print the result: the orchestrator, Prime, or your own agent definition, with text or JSON output.

<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 -p` gives Helix a task in a cloud sandbox and prints the result. Use it from a script, a
CI job, or a terminal when you need one result and do not need to send follow-up messages.

## Before you start

* You are signed in and a workspace is selected. See
  [LLM providers and models](/helix/cloud/setup#before-you-start).
* The workspace has an LLM provider and a default model: in `mutagent helix models --json`,
  `default` is not `null`. Otherwise pass `--model <provider/model>` from that list.
* Cloud sandboxes are enabled for your account (early access).

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

Helix completes the task, making as many model and tool calls as it needs, prints the final answer,
and exits. The run uses the workspace's LLM providers and default model.

On stderr, the CLI first prints the session reference:

```text theme={null}
[mutagent] Session hs1_<…>. Ctrl-C stops the session (SIGINT).
```

Keep it: `mutagent helix session attach`, `send`, `signal` and `checkpoint` take it. The final answer
goes to stdout, and the exit code is 0 when Helix ended normally.

## Choose what runs

| Command | What runs |
| - | - |
| `mutagent helix -p "<task>"` | The Helix orchestrator, with its lifecycle stages and sub-agents. |
| `mutagent helix --prime -p "<task>"` | The Prime agent. |
| `mutagent helix agent "<definition>" -p "<task>"` | Your own agent, without the orchestrator. |
| `mutagent helix agent "<definition>" --prime -p "<task>"` | Your own agent as the Prime agent. |

See [Three ways to run Helix](/helix/modes) for when to use each one.

## Your own agent: definition and task

`mutagent helix agent` takes two inputs:

* The **definition** says who the agent is: the first argument, `--prompt`, `--file`, or `--name`.
* The **task** says what to do: `-p "<task>"`, or a message after `--mode json`.

A definition with no task is refused, and the error tells you to add `-p`.

```bash theme={null}
# Definition as the first argument
mutagent helix agent "You explain programming concepts briefly." -p "Explain a closure."

# Definition from a file on your machine, JSON events out
mutagent helix agent --file ./agents/explainer.md --mode json "Explain a closure."

# Definition by name
mutagent helix agent --name explainer -p "Explain a closure."

# No definition: a general-purpose agent
mutagent helix agent -p "Explain a closure."
```

| Definition | Where it comes from |
| - | - |
| First argument or `--prompt "<text>"` | The text you pass. |
| `--file <path>` | Read on your machine; its contents are sent. A missing file is refused before anything starts. |
| `--name <name>` | Your local agent directories first, then the agents built into the cloud sandbox. An unknown name is refused. |
| None | A general-purpose agent. |

`--file` sends the definition only, not the tools, skills, or files it refers to.

## Options

| Option | What it does |
| - | - |
| `--model <provider/model>` | Use this model instead of the workspace default. It must be listed by `mutagent helix models`. A managed agent uses the model its package declares. |
| `--env <name>` | Load an [Environment](/helix/cloud/environments). |
| `--sandbox-provider <name>` | Run on another configured sandbox provider. An unknown name is refused, and the error lists the names you can use. |
| `--preset <name>` | Start the sandbox from this preset instead of the default one. See `mutagent sandbox presets`. |
| `--cwd <path>` | Working directory inside the sandbox. |
| `--repository <owner/name>` | Run in a checkout of this GitHub repository, through the workspace's GitHub connection. The checkout is the working directory, so `--cwd` is refused with it. See [Connecting GitHub and Slack](/helix/gateway/connect). |
| `--branch <name>` | The branch of `--repository` to check out. Default: its default branch. |
| `--thinking`, `--tools`, `--exclude-tools`, `--no-tools` | Work as they do in local Helix. |

The sandbox does not have your files. `--system-prompt` and `--append-system-prompt` read their file
on your machine and send the text. `--extension`, `--skill`, `--session`, `--continue`, `--resume`,
and `@file` arguments are refused, with a message that says what to do instead. Model keys are
refused on the command line; they come from your LLM providers.

## Output

| Mode | stdout |
| - | - |
| `-p "<task>"` | The final answer. |
| `--mode json "<task>"` | One JSON event per line. |

The CLI's own messages go to stderr, so you can redirect the answer:

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

The global `--json` flag does not change a run's output. Use `--mode json` for events.

## Exit status

Once the run has started, the CLI exits with Helix's exit status.

A launch that is refused before anything starts uses the CLI's exit codes: 1 for a refused launch
(for example `CLOUD_NOT_ENABLED`, a missing model, or a flag the cloud does not accept), 2 when your
Mutagent API key expired or is invalid, and 3 when you are not signed in or no workspace is
selected. With `-p`, the refusal is text on stderr. With `--mode json` or `--mode rpc`, it is one
JSON line on stderr with `code`, `error`, `suggestedAction` and `_agentGuidance.fix`; stdout stays
the session's. Run the fix it names; do not guess another command. See
[Troubleshooting cloud runs](/helix/cloud/troubleshooting) and [Errors and exit codes](/cli/errors).

In `--mode json`, exit code 0 means Helix ended normally, not that every model call succeeded. A
failed model call shows up as an assistant message with `stopReason: "error"` and an `errorMessage`.

## Stopping a run

| You do | What happens |
| - | - |
| Ctrl-C | The CLI sends SIGINT to Helix in the sandbox, waits for it to exit, and exits with its status, usually 130. |
| Your network connection fails | The run continues. Run the `session attach` command the CLI prints to watch it again. |
| `mutagent helix session signal <reference> --force` | Stops the run from another terminal. `--force` confirms the stop; without it nothing is sent. The reference is printed on stderr when the run starts. |

The sandbox keeps running after the run ends and stops 15 minutes after its last activity. If you need its files
afterwards, `mutagent helix session restore <reference>` restores it, with the reference printed on
stderr when the run started or listed by `mutagent helix session ls`. See [Idle sandboxes](/helix/cloud/sessions#idle-sandboxes).


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