Skip to main content
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 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.

​
Before you start

  1. Install the CLI and sign in. 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.
  4. Optional: create an Environment if the task needs variables or secrets, and connect GitHub with mutagent 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.
Takes the mode flags, placement and model flags, and Helix flags.

​
mutagent helix —prime

Run the Prime agent.
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.
With no definition, a general-purpose agent runs. Also takes the mode flags, placement and model flags, and 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.
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

Every run prints its session reference, which starts with hs1_, on stderr. Use it with mutagent 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.

​
Placement and model flags

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.

​
Helix flags

These flags work as they do in local Helix. 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.

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

​
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. 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 and CLI errors.