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

# mutagent helix session

> List, watch, send commands to, stop, checkpoint, and restore Helix Cloud sessions from any terminal.

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

These commands work on cloud sessions that already exist, from any terminal.

**Before you start:** [install the CLI](/cli/installation) and [sign in](/cli/commands/login) 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](/cli/commands/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.

```bash theme={null}
mutagent helix session list --json
```

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.

| Column | Meaning |
| - | - |
| `REFERENCE` | The `hs1_` reference that every session command takes. |
| `SANDBOX` | The ID of the sandbox the session runs in. |
| `AGENT` | `slug:vN` for a session run from a [managed agent](/helix/cloud/managed-agents), blank otherwise. |
| `ARM` | What runs: `classic` (the orchestrator), `prime`, or `agent`. |
| `MODE` | `interactive` for a session started with `--mode rpc` or `--rpc`, `headless` for a task run with `-p` or `--mode json`. |
| `STATUS` | `live` (running now), `ended` (finished; `--json` has its exit code), `stopped-for-idling` (its sandbox was idle for 15 minutes and was stopped), or `restored` (running in a sandbox rebuilt from a checkpoint). |
| `LAST ACTIVITY` | When the session last did something. |

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

```bash theme={null}
mutagent helix session attach <reference>
```

| Flag | What it does |
| - | - |
| `--since <n>` | Start after output number `n`. The CLI prints this number when a connection ends. |

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

```bash theme={null}
mutagent helix session send <reference> "Now run the tests."
mutagent helix session send <reference> --type steer "Only fix the failing test."
mutagent helix session send <reference> --type abort
```

| Flag | What it does |
| - | - |
| `--type <type>` | `prompt` (the default) starts a new instruction. `steer` changes the turn in progress. `follow_up` continues from the agent's last answer. `abort` ends the current turn and takes no message. |
| `--line <json>` | Send this JSON command as it is, instead of building one from `--type` and a message. |
| `--message-id <id>` | Use this ID for the command instead of a generated one. The answer carries the same ID. |

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

```bash theme={null}
mutagent helix session signal <reference> --force
```

| Flag | What it does |
| - | - |
| `--type <SIGINT\|SIGTERM>` | `SIGINT` (the default) or `SIGTERM`. Both stop the session's Helix process; the sandbox keeps running. To end only the current turn, use `send --type abort`. `SIGKILL` is not supported. |
| `-f, --force` | Required. Confirms the stop. |

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.

```bash theme={null}
mutagent helix session close-input <reference>
```

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.

```bash theme={null}
mutagent helix session checkpoint <reference> --json
```

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

```bash theme={null}
mutagent helix session checkpoints <reference>
```

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

```bash theme={null}
mutagent helix session restore <reference> --json
```

With `--json`, `reference` is the new session: use it for `attach`, `send`, `signal` and
`checkpoint`. Read `notRestored` before you rely on the restored state.

| Flag | What it does |
| - | - |
| `--snapshot <id>` | Restore this checkpoint, from `session checkpoints`, instead of the newest complete one. |
| `--on-drift <warn\|refuse\|skip>` | When the transcript names files that are missing: restore and list them (`warn`, the default), stop before restoring (`refuse`), or do not check (`skip`). |
| `--partial` | Also restore turns saved after the last checkpoint. The transcript may end with a tool call that has no result. |

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](/helix/cloud/sessions) for idle
stops and restore details.

## If it fails

| Exit code or error | Fix |
| - | - |
| `3` (`AUTH_REQUIRED`, `WORKSPACE_REQUIRED`) | [Sign in](/cli/commands/login) and select the session's workspace with `mutagent workspaces use <workspace-name>`. |
| `2` (`AUTH_EXPIRED`, `INVALID_API_KEY`) | Sign in again, or set a valid `MUTAGENT_API_KEY`. |
| Session not found (exit 1) | The reference is wrong, or the session is in another workspace. Copy it from `mutagent helix session list --json`. |
| `send` refused (exit 1) | The session is headless (`-p` or `--mode json`), has ended, or its input is closed. Only a live `--mode rpc` session takes input. |
| `checkpoint` refused (exit 1) | The session has not finished its first turn yet. Try again after it has. |
| `CONFIRMATION_REQUIRED` (exit 1) | `signal` needs `--force`. |

More cases: [Troubleshooting cloud runs](/helix/cloud/troubleshooting#sessions) and [CLI errors](/cli/errors).


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