Skip to main content
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.
For the platform model behind managed agents (agents, revisions, slots and runs), see Managed agents on the Platform. To build one step by step, follow the Quickstart; to write its tools, skills and files, see Tools, skills and files. A managed agent is an agent you write as a folder, deploy to your workspace, and run on Helix Cloud by its name:
This page assumes the setup in Helix Cloud: you are signed in, and the workspace has an LLM provider and a model list.

What a managed agent is

A managed agent is an address you pass to mutagent helix agent. It is not a separate runtime.
  • mutagent helix agent @invoice-pricing -p "…" starts the same way as every Helix Cloud run. It gets the same sandbox, model checks, idle policy and hs1_ session reference.
  • The difference from a definition passed as text or with --file: before Helix starts, the server copies the agent’s package into the sandbox. The package holds your prompt, tools, skills and files.

The agent.md format

Every field, its type, default and validation rule is in the agent.md reference. An agent is a folder. agent.md is its entry file: YAML frontmatter, then a Markdown body. The body is the standing prompt for every task. The task you pass when you run the agent is separate. The entry file must be named agent.md, in lowercase.

Base fields

These fields are a complete local definition. mutagent helix agent --file reads them.

The harness block

Deployment settings go in one optional harness: block. mutagent agent check and mutagent agent deploy read it. mutagent helix agent --file ignores it. Paths are relative to the agent folder. A path outside the folder is refused.

A complete example

This agent prices invoices. It reads a pricing policy from a skill and calls a tool that reads a product catalog.
With this folder, the task “Price three widget units.” returns totalCents: 4164 and catalogVersion: catalog-v1, and the answer ends with cobalt-orchard. Rules for tool modules:
  • Write a tool with defineTool from @mutagent/agents/tools. The compiler bundles and registers it. You do not write a Helix extension.
  • A tool can import relative files inside the agent folder, node: built-ins and @mutagent/agents/tools. Nothing else. Third-party npm dependencies are not installed.
  • A tool reads packaged files through context.paths.assetRoot, never through a path on your machine.

Check and run on your machine

  • The compiler needs Bun 1.3.14 on your machine.
  • agent run needs Helix installed on your machine, and the API key of the LLM provider named in model, in your local Helix login or your environment variables. Signing in to Mutagent does not give Helix a model key.
  • agent run runs in a temporary copy of the compiled package on your machine. It does not run in a sandbox.
  • agent run creates no agent, revision or slot in the workspace.
agent run takes a file path. A slug is refused: agent run tells you that a managed agent runs with mutagent helix agent @slug.

Deploy and activate

What deploy does

1

Compile

Compiles the folder on your machine, as check does. You do not need to run pack first.
2

Create or reuse the agent

Creates the agent named by name, or uses the existing agent with that slug.
3

Upload

Uploads the package, and the server verifies its digests. New content becomes the next revision. Unchanged content uses its existing revision.
4

Validate

Checks the revision before it can run:
  • model is in the workspace model list (mutagent helix models).
  • The Environment named by --env exists in the workspace.
  • Every secret in harness.bindings.secrets sets required: false. required defaults to true.
  • The sandbox provider can receive a package. See Environments and slots.
5

Activate

Activates the revision in the slot. With --no-activate, deploy stops after validation: the revision exists and @slug:vN or @slug:latest runs it, but @slug still runs the previous active revision.

Update and roll back

To update, edit the folder and deploy again. New runs use the new active revision. A running session keeps the revision it started with. To roll back, activate an earlier revision:
activate runs the same validation as deploy: the model and the Environment are checked again.

Run a managed agent

Modes

-p with no task text is refused with exit code 1 before any request is sent. If you pass neither -p nor --rpc and the package sets harness.runtime.mode: headless, the run is refused with 422 before any sandbox starts, because a headless run needs a task.

What happens on a run

1

Find the revision

The server finds the agent by slug, then the slot for --env, then the revision: the active one, the vN you named, or the newest validated one for :latest.
2

Check before any sandbox starts

It checks that the model is in the workspace model list, that the Environment exists, and that the sandbox provider can receive a package.
3

Start the sandbox

It starts a sandbox on the default sandbox provider, or on the one named by --sandbox-provider. The sandbox gets the workspace’s LLM provider keys and the Environment’s variables, as on every run.
4

Copy the package

It copies the revision’s package into the sandbox and checks its digest.
5

Start the agent

It starts Helix with the package’s prompt, tools and skills. The tool module reports the tools it registered. If they do not match agent.md, the run stops.
6

Return the receipt

It sends the task (headless) or opens the session (interactive) and returns one receipt.

The receipt

The receipt includes: The CLI prints the receipt as one JSON line on stderr, before any output from the agent. Keep the reference: every session command takes it. The receipt says the session started. It does not contain the task’s result. Read the session’s events for the result.

Sessions

A managed agent’s session is addressed by its hs1_ reference. A managed agent’s sandbox follows the same idle policy as every sandbox: after 15 minutes with no activity, a final checkpoint is saved and the sandbox stops. Restoring a managed agent’s session is not supported yet, so start a new run after an idle stop. See Sessions for the session commands.

Environments and slots

  • A slot is one agent in one Environment. --env prod on deploy, activate, inspect, retire and helix agent names the same slot.
  • --env is optional on every command. Without it, the command uses the default slot, which has no Environment.
  • --env <name> must name an existing workspace Environment. deploy and activate check it.
  • On a run, --env <name> also loads that Environment’s variables and secrets into the sandbox, as on every run. See Environments.
  • Each slot has its own active revision. prod can run v2 while the default slot runs v4.
  • If an Environment is deleted, a run addressed to its slot is refused with 404, naming the Environment. mutagent agent inspect still lists the slot.
  • A run addressed to a retired slot is refused with 409 MANAGED_AGENT_SLOT_RETIRED, with a pinned revision or without.
A slot does not record a sandbox provider. Each run uses the default sandbox provider, or the one named by --sandbox-provider. Not every sandbox provider can receive a package yet. deploy, activate and a run refuse a sandbox provider that cannot, and the message names the sandbox provider.

Models

  • model is required in agent.md. check and deploy refuse a file without it.
  • A managed agent always uses its own model. The workspace default model is not used.
  • deploy and activate refuse a model that is not in the workspace model list (mutagent helix models).
  • A run checks the model again before any sandbox starts. If the LLM provider was deactivated after deploy, the run is refused and no sandbox starts.
  • The model’s API key comes from the workspace’s LLM provider and is added when the sandbox starts. deploy never uploads your local key.

Refused

The run refusals above happen before a sandbox starts. The tool registration check happens after the sandbox starts; when it fails, the sandbox it started is stopped.

Not built yet

mutagent agent

Every mutagent agent command and its flags.

Sessions

Watch, send to, stop and checkpoint a session.