> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mutagent.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Sessions

> Keep an interactive cloud Helix session running with --mode rpc, then list, watch, steer, stop, checkpoint, and restore it with mutagent helix session.

<Note>
  **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.
</Note>

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](/helix/cloud/agent-runs#before-you-start).

## Start an interactive session

```bash theme={null}
mutagent helix --mode rpc
```

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:

```text theme={null}
[mutagent] Session hs1_<…>. Ctrl-C stops the session (SIGINT).
```

The CLI forwards stdin to Helix and prints its responses and events on stdout, one JSON object per
line. Write one command per line:

```json theme={null}
{"type":"prompt","id":"task-1","message":"Explain the evaluation steps."}
{"type":"get_state","id":"state-1"}
```

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

```bash theme={null}
mutagent helix session ls
```

This lists every Helix session in the workspace, newest activity first:

| Column | Meaning |
| - | - |
| `REFERENCE` | The `hs1_` reference the session commands take. |
| `AGENT` | `slug:vN` for a session run from a [managed agent](/helix/cloud/managed-agents), blank otherwise. |
| `ARM`, `MODE` | What runs (`classic`, `prime`, `agent`) and how (`interactive`, `headless`). |
| `STATUS` | `live`, `ended`, `stopped-for-idling`, or `restored`. |
| `LAST ACTIVITY` | When the session last did something. |

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

```bash theme={null}
mutagent helix session attach <reference>
mutagent helix session send <reference> "Now run the tests."
mutagent helix session send <reference> --type steer "Focus on the failing test only."
mutagent helix session send <reference> --type follow_up "Summarize what you changed."
mutagent helix session send <reference> --type abort
mutagent helix session signal <reference> --force
mutagent helix session close-input <reference>
mutagent helix session checkpoint <reference>
```

| Command | Effect |
| - | - |
| `attach` | Prints the session's output and follows it. Read-only. `--since <n>` starts after output number `n`, which the CLI prints when you disconnect. Ctrl-C stops watching; the session keeps running. |
| `send` | Writes one command into the session: `prompt` (the default), `steer`, `follow_up`, or `abort`. `--line '<json>'` sends one raw JSON command instead. |
| `signal` | Sends SIGINT to Helix in the sandbox. `--type SIGTERM` sends SIGTERM instead. Both stop Helix; the sandbox keeps running. It needs `--force`, because it stops work in progress; without it the command refuses and sends nothing. |
| `close-input` | Closes the session's input, as closing stdin does. An interactive session finishes its current work and ends. |
| `checkpoint` | Saves a checkpoint now. It lists anything it could not capture. A session that has not finished a turn yet has nothing to save and is refused. |

`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

| You do | What happens |
| - | - |
| Close stdin of `mutagent helix --mode rpc` | Input to the session is closed after the queued lines are sent. |
| Ctrl-C on `mutagent helix --mode rpc` | SIGINT goes to Helix in the sandbox. The CLI waits for it to exit and exits with its status. |
| Ctrl-C on `session attach` | You stop watching. Nothing is sent to the session. |
| Your network connection fails | You stop watching. The session keeps running. The CLI prints a `session attach` command with `--since` that starts after the last output you received. |

## 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:

```bash theme={null}
mutagent helix session checkpoints hs1_…
mutagent helix session restore hs1_…
```

`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.

| Flag | Effect |
| - | - |
| `--snapshot <id>` | Restore this checkpoint instead of the newest one. |
| `--on-drift warn\|refuse\|skip` | What to do when the transcript names files that are not in the sandbox: restore and report them (`warn`, the default), stop before switching (`refuse`), or skip the check (`skip`). |
| `--partial` | Also restore turns captured after the last checkpoint. The transcript may end with a tool call that has no result. |

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.

<CardGroup cols={2}>
  <Card title="Agent runs" icon="user-gear" href="/helix/cloud/agent-runs">
    Definitions, tasks, output, and exit status.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/helix/cloud/troubleshooting">
    Errors you may see and what to do about them.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.