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.
These commands work on cloud sessions that already exist, from any terminal. Before you start: install the CLI and sign in to the workspace the session runs in (MUTAGENT_API_KEY=<key> mutagent login --json for a coding agent). A session in another workspace is reported as not found. Take references from the run’s stderr or from session list --json; never guess one. Pass --json to every command here except attach, whose output is Helix’s own. How a session works:
  1. Start a session with --mode rpc on mutagent helix. The CLI prints its reference, which starts with hs1_.
  2. session list lists it with its reference.
  3. attach, send, signal, close-input, checkpoint, checkpoints, and restore take the reference.
  4. After 15 minutes with no activity, the sandbox stops; an interactive session is checkpointed first.
  5. send wakes it and delivers your message, or restore starts it again. Either way it continues as a new session with a new reference.

​
mutagent helix session list

List every Helix session in the workspace, live and ended, newest activity first. mutagent helix session ls is the same command.
With --json: { "workspaceId", "sessions": [{ "reference", "sandboxId", "status", "agent", "arm", "mode", … }], "count" }. Pick the reference of a session whose status is live to send to it. ARM and MODE are blank for sessions older than those columns.

​
mutagent helix session attach

Print a session’s output and keep printing new output. Read-only. Ctrl-C stops watching; the session keeps running.

​
mutagent helix session send

Send one command into a session started with --mode rpc. The command confirms delivery; the agent’s answer appears in the session’s output, so run attach in another terminal to read it.
send does not wait for the answer. With --json, accepted: true means the command was delivered, not answered. A session that has ended refuses input. With --json, the command prints one object: { "success", "reference", "type", "id", "line", "accepted", "_links" }. id is the command ID; the answer is a response event with the same id on session attach. If the session’s sandbox was stopped because it was idle, send wakes it: the session is restored from its last checkpoint in a new sandbox, and your message is delivered once Helix is up. The restored session gets a new reference, which session list shows. Later sends to the old reference still reach the restored session.

​
mutagent helix session signal

Send a signal to Helix in the sandbox. Use it when send --type abort has no effect. The sandbox keeps running, with its files and output, so attach still shows what the session did. Stopping a session stops work in progress, so the command needs --force, like a delete. Without it, the command refuses and sends nothing.
With --json: { "success", "reference", "signal", "signalled", "_links" }. signalled is true only when a running process was stopped. Without --force, the command exits 1 with CONFIRMATION_REQUIRED and sends nothing; a coding agent confirms with the person before adding --force. If the session had already ended, the command exits with code 1. The session is already stopped, so there is nothing to retry.

​
mutagent helix session close-input

Close a session’s input, as closing stdin does on mutagent helix --mode rpc. An interactive session finishes its current work and ends; session send is refused afterwards. Closing input that is already closed succeeds.
Closing input is not a signal. To stop the session, use session signal; to end only the current turn, use session send --type abort.

​
mutagent helix session checkpoint

Save a checkpoint of a session now: its transcript and, where they can be captured, its files and settings. The output lists anything that was not captured. A session that has not finished a turn has nothing to save and is refused.
With --json, keep snapshotId and read notCaptured before you rely on a restore. For an interactive session, checkpoints are also saved each time a turn finishes and when its idle sandbox stops. Headless runs are not checkpointed.

​
mutagent helix session checkpoints

List the checkpoints of the sandbox a session runs in, newest first. The list covers every session that sandbox has run: SESSION names each checkpoint’s session and MESSAGES shows how much conversation it holds. Pass a checkpoint’s ID to restore --snapshot.

​
mutagent helix session restore

Continue a session from a checkpoint in a rebuilt sandbox. The session’s sandbox may be stopped or gone. restore starts a new session that continues the conversation and prints its reference; the old reference stops working. session list shows the new session with status restored.
With --json, reference is the new session: use it for attach, send, signal and checkpoint. Read notRestored before you rely on the restored state. A managed agent’s session cannot be restored yet: restore is refused with HTTP 409 MANAGED_AGENT_RESTORE_UNSUPPORTED. Start a new run with mutagent helix agent @<slug>. Lines printed in yellow name what was not restored. See Sessions for idle stops and restore details.

​
If it fails

More cases: Troubleshooting cloud runs and CLI errors.