Cloud sandboxes

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.

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.

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.
The LLM providers	The workspace’s active LLM providers 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.

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 with a workspace selected:

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

Sessions

Watch, send to, stop, checkpoint and restore a session.

Sandbox providers

Where a sandbox runs, and what a sandbox provider decides.

Overview

Sandbox

Managed agents

Setup

What the platform manages

What you control

Sessions

Sandbox providers

​What the platform manages

​What you control

Sessions

Sandbox providers

What the platform manages

What you control