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

# Cloud sandboxes

> What a cloud sandbox is on the platform, what the platform manages for it, and what you control.

<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 cloud sandbox is an isolated Linux machine that the platform starts for a Helix Cloud session or a
managed agent run. Helix runs inside it.

* It has the API keys of the workspace's active LLM providers, and the variables and secrets of the
  Environment the run loads with `--env`.
* A managed agent run also has the agent's package: its prompt, tools, skills and files.
* You address the session in it by its session reference, which starts with `hs1_`. A restore, or a
  wake after an idle stop, starts a new session, so it has a new reference. Messages sent to the old
  reference still reach it.

Sandboxes are managed by the platform. You work with the session in a sandbox through
`mutagent helix` and `mutagent helix session`; you do not sign in to the machine.

```mermaid theme={null}
flowchart LR
  LLM["LLM providers: model keys"] --> SBX["Cloud sandbox"]
  ENV["Environment: variables and secrets"] --> SBX
  PKG["Managed agent package"] --> SBX
  SBX --> H["Helix session: hs1_ reference"]
  classDef s fill:#140d22,stroke:#7E47D7,color:#ede7f8;
  class LLM,ENV,PKG,SBX,H s;
```

## What the platform manages

| | What happens |
| - | - |
| Placement | Each run starts a sandbox on the default sandbox provider, or on the one named by `--sandbox-provider`. |
| Start | The platform starts the machine, adds the LLM provider keys and the Environment, and starts Helix. For a managed agent run, it copies the package in and checks its digest first. |
| Checkpoints | For an interactive session, a checkpoint is saved each time a turn finishes, when an idle sandbox stops, and when you run `session checkpoint`. It holds the session transcript and, where the sandbox provider supports it, the working directory and the session settings. A headless run (`-p` or `--mode json`) is not checkpointed. |
| Idle stop | After 15 minutes with no activity, the sandbox stops. An interactive session in it is checkpointed first. A turn the agent is still working on counts as activity, for up to 4 hours. `session ls` shows the session as `stopped-for-idling`. |
| Wake on send | Sending a message to a session stopped for idling wakes it: the platform restores it and then delivers your message, and the conversation carries on in the same thread. The web app shows **Waking up…** until the session is back. |
| Restore | `session restore` starts a new sandbox from a checkpoint and starts a new session that continues the conversation. The stopped sandbox does not need to be running. |
| Cleanup | A stopped sandbox is removed from its sandbox provider. A sandbox that its sandbox provider no longer runs is marked stopped, and you can restore its session. |

If the final checkpoint could not be saved, restore uses the newest checkpoint that was saved.

## What you control

| You choose | How |
| - | - |
| The Environment | `--env <name>` loads a workspace Environment's variables and secrets. See [Environments](/helix/cloud/environments). |
| The LLM providers | The workspace's active [LLM providers](/platform/providers/overview) supply the model keys. Every active one is added to the sandbox. |
| The model | `--model`, the workspace default model, or, for a managed agent, the model its package names. |
| The sandbox provider | Mutagent Cloud (`mutagent-cloud`), the default and the only one available now. Other sandbox providers are coming soon. See [Sandbox providers](/platform/sandbox/providers). |

Model keys do not go in an Environment. Names the platform sets in the sandbox are reserved, and an
Environment cannot override them. `mutagent env set` refuses a variable named like an LLM provider
key, such as `ANTHROPIC_API_KEY`.

To see what a run will get, check each input from the CLI. Each needs a
[sign-in](/cli/commands/login) with a workspace selected:

```bash theme={null}
mutagent providers list --json          # the LLM providers
mutagent helix models --json            # the model ids, and the workspace default model
mutagent env list --json                # the Environments: names and fingerprints, never values
mutagent sandbox providers --json       # the sandbox providers and the default
```

<CardGroup cols={2}>
  <Card title="Sessions" icon="comments" href="/helix/cloud/sessions">
    Watch, send to, stop, checkpoint and restore a session.
  </Card>

  <Card title="Sandbox providers" icon="server" href="/platform/sandbox/providers">
    Where a sandbox runs, and what a sandbox provider decides.
  </Card>
</CardGroup>


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