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

# Helix Cloud

> Run Helix in a cloud sandbox. Store tool secrets in an Environment, connect your LLM providers, then run a task or keep a session running.

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

Helix Cloud runs Helix in a cloud sandbox instead of on your machine. A run continues if you
disconnect, and a script can start one with a single command.

A cloud run uses the four things below. You set up the first three once per workspace. The fourth is
the command you run.

| | What it is for | What you do |
| - | - | - |
| [Environments](#environments) | Variables and secrets your agent's tools need | Optional: `mutagent env set` |
| [Sandbox providers](#sandbox-providers) | Where your sessions run | Nothing. Mutagent's sandboxes are the default. |
| [LLM providers](#llm-providers) | The models your sessions call | `mutagent providers mirror` |
| [Helix Cloud](#run-helix-in-the-cloud) | Running Helix on a task or as a live session | `mutagent helix -p "<task>"` |

Start by signing in:

```bash theme={null}
mutagent login
```

## Environments

An Environment holds the variables and secrets your cloud sessions need, such as a GitHub token or a
database URL. Your local shell variables are not sent to the sandbox, so anything a tool reads from its
environment goes here.

```bash theme={null}
mutagent env set ci DATABASE_URL=<database-url> --secret GITHUB_TOKEN=<github-token>
mutagent env ls
```

Load it into a run with `--env ci`. Environments belong to the workspace. Secrets are stored
encrypted and are never shown again.

Model keys do not go in an Environment. They come from your LLM providers.

[More on Environments](/helix/cloud/environments)

## Sandbox providers

A sandbox provider is where your cloud sessions run. Mutagent runs them in its own sandboxes, so there
is nothing to set up. [More on sandbox providers](/helix/cloud/sandbox-providers)

## LLM providers

Your sessions call your models with your own API keys, so the workspace needs your LLM providers. If
Helix already works on your machine, copy its setup:

```bash theme={null}
mutagent providers mirror
mutagent helix models
```

`providers mirror` shows what it will copy and asks first. It copies your API keys and model lists
into the workspace and, if the workspace has no default model yet, sets one. `helix models` lists the
models your sessions can use and marks the default with ★.

Without a local Helix setup, add an LLM provider directly:

```bash theme={null}
mutagent providers add --provider anthropic --name "Anthropic" --api-key <api-key>
```

A run with no model available is refused before any sandbox starts.

[More on LLM providers and models](/helix/cloud/setup)

## Run Helix in the cloud

You can run Helix in two ways.

### Run a task

```bash theme={null}
mutagent helix -p "Plan an evaluation for a support-triage agent."
mutagent helix agent "You write release notes." -p "Write release notes for version 1.2."
```

Helix completes the task, making as many model and tool calls as it needs, prints the final answer,
and exits. The sandbox stops 15 minutes after the run's last activity. If you need its files
afterwards, `mutagent helix session restore <reference>` restores it, using the `hs1_` reference the
run printed.

* `mutagent helix` runs the Helix orchestrator.
* `mutagent helix agent "<definition>"` runs your own agent instead.
* Add `--prime` to either one to use the Prime agent.
* Use `--mode json` instead of `-p` to get events, one JSON object per line.

[More on running a task](/helix/cloud/agent-runs)

### Run a session

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

For your own agent, use `mutagent helix agent "<definition>" --rpc`. The session keeps running and
reads commands from stdin. The CLI prints the session's reference, which starts with `hs1_`. Use it from any
terminal:

```bash theme={null}
mutagent helix session ls
mutagent helix session attach <reference>
mutagent helix session send <reference> "Now run the tests."
```

After 15 minutes with no activity, the sandbox stops; an interactive session is checkpointed first. A
turn the agent is still working on counts as activity, for up to 4 hours. To continue, just send it a
message: the session wakes on a new sandbox from its last checkpoint and gets your message, under the
same reference:

```bash theme={null}
mutagent helix session send hs1_… "carry on"
```

There is no terminal chat client for a cloud session. Use `-p` for a task, or `--mode rpc` and
`session send` for a session.

[More on sessions](/helix/cloud/sessions)

### Run a managed agent

The orchestrator, Prime and your own agent definition are three things you can run. The fourth is a
managed agent: an agent you write as an `agent.md` folder with its own tools, skills and files,
deploy to the workspace, and run by its address, as a task with `-p` or as a session with `--rpc`.

```bash theme={null}
mutagent agent deploy invoice/agent.md
mutagent helix agent @invoice-pricing -p "Price three widget units."
```

[More on managed agents](/helix/cloud/managed-agents)

### Options for tasks and sessions

| Option | Effect |
| - | - |
| `--model <provider/model>` | Use this model instead of the workspace default. It must be listed by `mutagent helix models`. A managed agent uses the model its package declares. |
| `--env <name>` | Load an Environment. |
| `--sandbox-provider <name>` | Run on this sandbox provider instead of the default. |
| `--preset <name>` | Start the sandbox from this preset instead of the default one. See `mutagent sandbox presets`. |
| `--cwd <path>` | Working directory inside the sandbox. |

Your repository and local files are not uploaded. The agent works inside the sandbox.

<CardGroup cols={2}>
  <Card title="LLM providers and models" icon="key" href="/helix/cloud/setup">
    Mirror, add an LLM provider, and choose the default model.
  </Card>

  <Card title="Sessions" icon="comments" href="/helix/cloud/sessions">
    Send, watch, stop, checkpoint, and restore a session.
  </Card>

  <Card title="Command reference" icon="terminal" href="/cli/commands/helix">
    Every Helix command and its flags.
  </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.