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.
What a managed agent is
A managed agent is an address you pass tomutagent 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 andhs1_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 optionalharness: 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.totalCents: 4164 and
catalogVersion: catalog-v1, and the answer ends with cobalt-orchard.
Rules for tool modules:
- Write a tool with
defineToolfrom@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 runneeds Helix installed on your machine, and the API key of the LLM provider named inmodel, in your local Helix login or your environment variables. Signing in to Mutagent does not give Helix a model key.agent runruns in a temporary copy of the compiled package on your machine. It does not run in a sandbox.agent runcreates 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:
modelis in the workspace model list (mutagent helix models).- The Environment named by
--envexists in the workspace. - Every secret in
harness.bindings.secretssetsrequired: false.requireddefaults totrue. - 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 itshs1_ 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 prodondeploy,activate,inspect,retireandhelix agentnames the same slot. --envis optional on every command. Without it, the command uses the default slot, which has no Environment.--env <name>must name an existing workspace Environment.deployandactivatecheck 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.
prodcan runv2while the default slot runsv4. - If an Environment is deleted, a run addressed to its slot is refused with 404, naming the
Environment.
mutagent agent inspectstill lists the slot. - A run addressed to a retired slot is refused with 409
MANAGED_AGENT_SLOT_RETIRED, with a pinned revision or without.
--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
modelis required inagent.md.checkanddeployrefuse a file without it.- A managed agent always uses its own
model. The workspace default model is not used. deployandactivaterefuse 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.
deploynever 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.