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.
A headless run (-p) ends when the task is done. An interactive session keeps Helix running in the sandbox and reads commands until you close its input or stop it. Before you start: you need what a headless run needs. See Run a task.

​
Start an interactive session

The same works for Prime, mutagent helix --prime --mode rpc, and for your own agent, mutagent helix agent "<definition>" --rpc. The CLI prints the session reference on stderr:
The CLI forwards stdin to Helix and prints its responses and events on stdout, one JSON object per line. Write one command per line:
An interactive session ignores positional messages; send the task as a prompt command. Input is sent in order, and the CLI never sends a line twice when it reconnects. When stdin reaches end-of-file, the CLI closes the session’s input after the queued lines are sent. Closing input is not a signal. A pipe from a program that exits closes stdin, so keep stdin open for as long as you want to send commands.

​
The session reference

Every launch prints a reference that starts with hs1_. Every session command below takes it, including checkpoints and restore. The reference points at one session. A restore starts a new session with a new reference, and the old reference stops working.

​
List sessions

This lists every Helix session in the workspace, newest activity first: Add --json for the same data as one object: { workspaceId, sessions: [{ reference, sandboxId, status, agent, arm, mode, … }], count }. A coding agent takes references from here or from the launch; never guess one.

​
Watch, steer, and stop a session

send confirms that the command was delivered, not that the agent answered. With --json it returns { success, reference, type, id, line, accepted }: accepted means delivered. The answer is a response event with the same id on the session’s output, so attach in another terminal first if you want to see it. Only interactive sessions, started with --mode rpc or --rpc, accept send; a headless run (-p or --mode json) can be watched but not written to. abort ends the current turn and keeps the session running. signal also works on a process that has stopped reading its input.

​
Stopping and disconnecting

​
Checkpoints and restore

Helix Cloud checkpoints an interactive session each time a turn finishes and when its idle sandbox stops. session checkpoint <reference> saves one immediately. A checkpoint holds the session transcript and, where supported, the working directory and the session settings. Headless runs are not checkpointed. checkpoints and restore take the session reference, like every session command:
checkpoints lists the checkpoints of the sandbox the session runs in, newest first. restore rebuilds the sandbox, puts the files and the transcript back, starts a new session that continues the conversation, and prints the new reference. The sandbox does not need to be running. The old reference stops working; mutagent helix session ls lists the restored session with status restored. A managed agent’s session cannot be restored yet: restore is refused with HTTP 409 MANAGED_AGENT_RESTORE_UNSUPPORTED. Start a new run instead. Read the lines restore prints in yellow. Each one names something that was not restored, such as the workspace files when they were not captured. Without these lines, a restore of only the conversation is indistinguishable from a full restore. A restore does not undo side effects of a tool call that was interrupted.

​
Idle sandboxes

A sandbox that is idle for 15 minutes is stopped. An interactive session in it is checkpointed first.
  • What counts as activity: starting a session, send, signal, checkpoint, restore, and an open session attach. A turn the agent is still working on also counts, for up to 4 hours.
  • At 15 minutes idle: an interactive session is checkpointed, then the sandbox stops. session ls shows the session as stopped-for-idling.
  • Getting it back: just send. mutagent helix session send <reference> "…" to a session stopped for idling wakes it: the session is restored onto a new sandbox from its last checkpoint, and your message is delivered once Helix is up. You keep using the same reference; later sends to it reach the woken session. Messages sent while it wakes are queued and delivered once each, in the order you sent them. A wake usually takes a few seconds, longer when the session has a repository.
  • Restoring by hand: mutagent helix session restore <reference> still works, for example to pick an older checkpoint with --snapshot. It prints the new reference.
  • What is not woken: a headless run has no checkpoint; run it again. A session that ended, was stopped with session signal, or whose sandbox was removed stays ended.
  • While a sandbox is stopping: for a few seconds, requests to it are refused with HTTP 409 and a request to retry shortly. session restore waits and retries once by itself.
If the final checkpoint could not be saved, restore uses the newest checkpoint that was saved. That can be older than the moment the sandbox stopped, so checkpoint a session whenever it is in a state you want to keep.

Agent runs

Definitions, tasks, output, and exit status.

Troubleshooting

Errors you may see and what to do about them.