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

> List the sandbox providers and presets a Helix Cloud run can name with --sandbox-provider and --preset.

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

Every Helix Cloud run starts a cloud sandbox. These two commands show what a run can choose from:
the sandbox provider it runs on, and the preset it starts from. Both lists are the same for every
workspace, because sandbox providers are part of the platform. LLM providers and Environments, by
contrast, belong to each workspace.

You do not need either command to start a run: without a flag, a run uses the default of each.

**Before you start:** [install the CLI](/cli/installation), [sign in](/cli/commands/login)
(`MUTAGENT_API_KEY=<key> mutagent login --json` for a coding agent), and select a workspace with
`mutagent workspaces use <workspace-name>`.

```bash theme={null}
mutagent sandbox providers
mutagent sandbox presets
mutagent helix --sandbox-provider mutagent-cloud --preset mutagent-sandbox -p "<task>"
```

## mutagent sandbox providers

List the sandbox providers that `mutagent helix --sandbox-provider <name>` accepts, and mark the
default.

```bash theme={null}
mutagent sandbox providers
mutagent sandbox providers --json
```

```text theme={null}
NAME            DEFAULT
--------------  -------
mutagent-cloud  yes

1 result(s)
```

With `--json`, the command prints one object:

```json theme={null}
{
  "providers": ["mutagent-cloud"],
  "default": "mutagent-cloud",
  "count": 1
}
```

`mutagent-cloud` (shown as Mutagent Cloud in the web app) is the platform's own sandbox provider
and the default for every run. A sandbox provider is where a sandbox runs. It is not an LLM provider (`mutagent providers`) and not
an Environment (`mutagent env`). A run that names a sandbox provider not in this list is refused
before anything starts, and the error lists the names you can use. See
[Sandbox providers](/helix/cloud/sandbox-providers).

## mutagent sandbox presets

List the presets that `mutagent helix --preset <name>` accepts, and mark the default. A preset is a
named sandbox definition kept on the platform: what the sandbox runs, its CPU architecture, and the
sandbox provider it runs on.

```bash theme={null}
mutagent sandbox presets
mutagent sandbox presets --json
```

```text theme={null}
NAME              DEFAULT  ARCH   PROVIDER        DESCRIPTION
----------------  -------  -----  --------------  --------------------
mutagent-sandbox  yes      arm64  mutagent-cloud  Helix runtime image

1 result(s)
```

With `--json`, the command prints one object:

```json theme={null}
{
  "presets": [
    {
      "name": "mutagent-sandbox",
      "description": "Helix runtime image",
      "arch": "arm64",
      "provider": "mutagent-cloud"
    }
  ],
  "default": "mutagent-sandbox",
  "count": 1
}
```

| Field | Meaning |
| - | - |
| `presets[].name` | The name to pass as `--preset`. |
| `presets[].description` | What the preset runs. |
| `presets[].arch` | The CPU architecture. |
| `presets[].provider` | The sandbox provider the preset runs on, when it names one. |
| `default` | The preset a run uses when it names none, or `null`. |

An unknown preset name is refused before anything starts.

## In scripts

Read the list before you pass a name, so a run is not refused:

```bash theme={null}
provider=$(mutagent sandbox providers --json | jq -r '.default')
mutagent helix --sandbox-provider "$provider" -p "Summarize the open pull requests."
```

## If it fails

| Exit code or error | Fix |
| - | - |
| `3` (`AUTH_REQUIRED`, `WORKSPACE_REQUIRED`) | [Sign in](/cli/commands/login), then `mutagent workspaces use <workspace-name>`. |
| `2` (`AUTH_EXPIRED`, `INVALID_API_KEY`) | Sign in again, or set a valid `MUTAGENT_API_KEY`. |
| A run is refused for an unknown sandbox provider or preset (exit 1) | Copy a name from `mutagent sandbox providers --json` or `mutagent sandbox presets --json`, or leave the flag out. |
| A run is refused with `CLOUD_NOT_ENABLED` (exit 1) | Run `mutagent sandbox access --json`. If it prints `{"cloudSandboxes": false}`, cloud sandboxes are not enabled for your account yet; do not retry the run. |

See [CLI errors](/cli/errors).

`mutagent sandbox` has other subcommands for running commands in a sandbox directly. Agent tasks use
[mutagent helix](/cli/commands/helix). Run `mutagent sandbox --help` for the full list.


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