Run a task

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.

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

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:

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

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

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 and Errors and exit codes. 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.

Get started

Run it

Lifecycle

Features

Helix Cloud

Reference

Before you start

Choose what runs

Your own agent: definition and task

Options

Output

Exit status

Stopping a run

​Before you start

​Choose what runs

​Your own agent: definition and task

​Options

​Output

​Exit status

​Stopping a run

Before you start

Choose what runs

Your own agent: definition and task

Options

Output

Exit status

Stopping a run