> ## 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 an interactive
  session a message and it wakes up, delivers your message and carries on in the same conversation.
  A `-p` task run cannot be woken; run it again.
</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` |
| [Run Helix](#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}
printf 'GITHUB_TOKEN=%s\n' "$GITHUB_TOKEN" > .env.ci.secrets   # keep secrets off the command line
mutagent env set ci DATABASE_URL=<database-url> --secrets-from-file .env.ci.secrets
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. From a script or coding agent, run
`mutagent providers mirror --json` to see the plan without sending anything, then
`mutagent providers mirror --yes --json` to apply it. 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}
printf '%s' "$ANTHROPIC_API_KEY" | mutagent providers add --provider anthropic --name "Anthropic" --api-key-stdin
```

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. A task run (`-p`) is not
checkpointed and cannot be restored: its files go when the sandbox stops. When you need to restore the
work later, run it as a session (`--mode rpc`) instead.

* `mutagent helix` runs the full Helix session, with its lifecycle stages and sub-agents.
* `mutagent helix agent "<definition>"` runs your own agent instead (agent mode).
* Add `--prime` to either one to use Prime, the experimental code-first mode.
* 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` (`--rpc` is the short form of
`--mode 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 full Helix session (`mutagent helix`), Prime (`--prime`) and your own agent definition
(`mutagent helix agent`) 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.