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 an interactive
session a message and it wakes up, delivers your message and carries on in the same conversation.
A
-p task run cannot be woken; run it again.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:
- Start a session with
--mode rpcon mutagent helix. The CLI prints its reference, which starts withhs1_. session listlists it with its reference.attach,send,signal,close-input,checkpoint,checkpoints, andrestoretake the reference.- After 15 minutes with no activity, the sandbox stops; an interactive session is checkpointed first.
sendwakes it in a new sandbox from its last checkpoint and delivers your message. Keep using the same reference.restorestarts it again as a new session with a new reference; the old reference stops working.
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.
--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 whensend --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 onmutagent helix --mode rpc. An interactive session
finishes its current work and ends; session send is refused afterwards. Closing input that is
already closed succeeds.
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.--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.
--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.