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.
Most refusals happen on your machine, before anything starts, and end with exit code 1 and a line that says what to do instead. Errors returned by the platform include an HTTP status. If a launch fails after it printed a session reference, the session may still be running: check mutagent helix session ls before you start the task again. Before a run starts, the CLI’s exit codes apply: 0 success, 1 failure (usage errors included), 2 your Mutagent API key expired or is invalid, 3 not signed in or no workspace. Once a run has started, the exit code is Helix’s own. With --mode json or --mode rpc, a refused launch is one JSON line on stderr; run what its _agentGuidance.fix names. See Errors and exit codes.

​
Sign-in and workspace

Run mutagent login. Without a browser, set MUTAGENT_API_KEY and run mutagent login --json. A coding agent helping a person runs mutagent login --browser --json and shows them the printed URL; the CLI waits up to 5 minutes. See Sign in.
Sign in again with mutagent login, or set a valid MUTAGENT_API_KEY. Mutagent keys start with mg_live_.
Helix Cloud is in early access and is not open to every account yet: we are letting accounts in gradually while we test. The launch was refused with code CLOUD_NOT_ENABLED and exit code 1, and nothing was started. Local Helix, mutagent agent check, pack and run work without it.
After mutagent helix, --api-key would be read as your Mutagent platform key and sent to the platform. Model keys belong to the workspace’s LLM providers. To pass your Mutagent key, put it before the command, as in mutagent --api-key <mutagent-key> helix -p "<task>", or set MUTAGENT_API_KEY.
After mutagent helix, --endpoint would be read as the Mutagent platform address, and your platform key would be sent there. Put it before the command, as in mutagent --endpoint <url> helix …, or set MUTAGENT_ENDPOINT. An LLM provider’s endpoint is part of that LLM provider’s configuration.
To use another workspace for one command, pass --workspace <name-or-id> before the command. See Sign-in and workspaces.
Check the selected workspace with mutagent workspaces current. A session in another workspace is reported as not found.

​
Models

The error code is NO_PROVIDER_CONFIGURED. Nothing was started. Read the error message to see which of the two causes applies:
  1. No default model. The run named no --model, and mutagent helix models shows “No default set”. Pass --model <provider/model> for this run, or set a default: mutagent helix models default <provider/model> [fallback …]. Any workspace member can set it.
  2. The model’s LLM provider is not configured (“Model X needs LLM provider Y, which this workspace has not configured”). Add the provider: mutagent providers add --provider <type> --name <name> --api-key-stdin, or copy your local Helix logins with mutagent providers mirror. Or pick a model whose provider is configured.
A coding agent should confirm with the user before adding a provider key. See LLM providers and models.
The --model value is not in the workspace’s list. Copy an ID exactly from mutagent helix models, in the form provider/model.
The cloud list comes from the workspace’s active LLM providers, not from your machine. Mirroring copies API keys and custom model declarations, but not OAuth logins, keys stored as references, or your local default model. Read the mirror report for skipped entries, then check both lists:
Entries after “Not usable by Helix Cloud” are LLM providers whose keys Helix cannot load into a sandbox.
The key or endpoint of the LLM provider is wrong or has no access to that model. Run mutagent providers test <id>, fix the LLM provider configuration, and run again. Do not put a model key into an Environment to work around it.In --mode json, a failed model call can still end with exit code 0. Look for an assistant message with stopReason: "error" and read its errorMessage.

​
Launch arguments

There is no terminal chat client for cloud sessions. Choose a mode: -p "<task>", --mode json "<task>", or --mode rpc. See Run Helix in the cloud.
The first positional argument of helix agent is the definition, not the task. Add the task with -p:
An interactive session ignores positional messages. Start with --mode rpc and no task, then write a prompt command to stdin:
--rpc means --mode rpc. Use one of them, not --rpc together with --mode json.
The sandbox does not have your files. --extension, --skill, --session, --continue, --resume, and @file arguments are refused. helix agent --file, --system-prompt, and --append-system-prompt read the file on your machine and send its contents. To give the agent other files, put what it needs into the task.
With --repository, the checkout is the working directory. Leave out --cwd. A managed agent (mutagent helix agent @<slug>) refuses --repository too.
--name looks in your local agent directories, then in the agents built into the cloud image. Check the name, or pass the definition with --file <path>.
--sandbox-provider takes the name of a sandbox provider configured for the platform. The error lists the names you can use. Leave the flag out to use the default.

​
Sessions

The session keeps running. Run the session attach command the CLI printed; its --since value starts after the last output you received. Reattaching never resends your input.
One of these applies:
  • The session is headless in the MODE column. -p and --mode json runs cannot receive input.
  • The session has ended, or its input was closed.
  • The sandbox is being stopped for idling. Wait a few seconds and send again: once it has stopped, a send wakes it.
Check the STATUS column of mutagent helix session ls.
stopped-for-idling means the sandbox had no activity for 15 minutes and was stopped; an interactive session was checkpointed first. Send it a message and it wakes, restored from that checkpoint, and gets the message:
HTTP 404 means the session can’t be woken: it was headless, it ended, or its sandbox was removed. Start a new run. mutagent helix session restore hs1_… restores an interactive session by hand. See Idle sandboxes.
A restore starts a new session with a new reference. Find it in mutagent helix session ls, where it has status restored.
The session runs a managed agent, and a managed agent’s session cannot be restored yet. Start a new run with mutagent helix agent @<slug>.
The session has not finished a turn yet, so there is no transcript to save. Send a prompt, wait for the turn to end, and checkpoint again.
Each line names something that was not restored, such as workspace files that were never captured. The conversation is restored; the named parts are not. With --on-drift refuse, a restore whose transcript names missing files stops before switching.
  • Ctrl-C on a launch sends SIGINT to Helix in the sandbox and waits for it to exit.
  • Ctrl-C on session attach only stops watching.
  • session send <reference> --type abort ends the current turn; the session keeps running.
  • session signal <reference> --force sends SIGINT, or SIGTERM with --type SIGTERM, even when Helix has stopped reading its input. Without --force it refuses and sends nothing.

​
Environments

The name matches a model key the workspace’s LLM providers already supply. For model access, fix the LLM provider instead. If you mean to override the key for runs that load this Environment, pass --allow-provider-key and store the value as a secret.
Rename the entry. See Which value is used.
Check mutagent env ls and the selected workspace. Environments belong to one workspace.
Pass at least one of KEY=VALUE, --secret KEY=VALUE, --from-file <path>, or --secrets-from-file <path>.
mutagent env rm <name> deletes the Environment and its secrets, mutagent env unset <name> <KEY> removes entries, and env set --replace removes every entry you did not name, so all three require --force. None of them asks for confirmation: without --force they exit 1 with CONFIRMATION_REQUIRED and change nothing.

​
LLM provider mirroring

Without a terminal, mirror cannot ask for confirmation, so it refuses and writes nothing. Exit code 1 is also used when at least one entry failed to copy; the report says which. Run mutagent providers mirror --json to see the plan, review it, then run it again with --yes.
You are not signed in, or no workspace is set. Run mutagent login and select a workspace.
OAuth and subscription logins, keys stored as references, and configurations with unsupported fields are not copied. The report gives the reason for each. Add those LLM providers with mutagent providers add instead. See Mirror your local Helix setup.