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,restoreandendtake 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. It takes no argument: to find one session, look for
its hs1_ reference in the listing.
--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
(Session restored as hs1_…); 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 whose checkpoint records no agent cannot be restored:
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.
mutagent helix session end
End a Helix session and remove the sandbox it runs in, addressed by itshs1_ session id.
Ending removes the sandbox and its files, with every other session on it, so a coding agent confirms
with the person before adding
--force. Without it, the command exits 1 with CONFIRMATION_REQUIRED
and sends nothing. Ending a session that has already ended succeeds. A session in a cloud sandbox may
end itself.
With --json: { success, session, ended, sandboxRemoved, checkpointSkipped }, plus alreadyEnded: true
when the session had already ended. If the end fails, the
error reads hs1_… was not ended: <reason>. Retry: mutagent helix session end hs1_… --force
(SESSION_END_FAILED).
If it fails
More cases: Troubleshooting cloud runs and CLI errors.