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.agent.md folder. check, pack and run work on your
machine. deploy, activate, list, inspect and retire work on
the workspace’s agents. Every command takes --json and then prints one result object on stdout.
To run a managed agent on Helix Cloud, use mutagent helix agent @<slug> on
mutagent helix. See Managed agents
for the agent.md format and a complete example.
How deployment works:
deploycompiles the folder and uploads it as a revision:v1,v2, and so on.- The revision becomes the active revision of a slot. A slot is one agent in one Environment;
without
--env, the default slot is used. mutagent helix agent @<slug>runs the slot’s active revision.activatemakes another revision active.retiredisables the slot.
Before you start
- Install the CLI.
check,pack,deployandruncompile the folder on your machine with Bun 1.3.14, on yourPATHor named byMUTAGENT_BUN_BIN.check,packandrunneed no sign-in. Every other command needs a sign-in and a selected workspace. A coding agent signs in withMUTAGENT_API_KEY=<key> mutagent login --json, then runsmutagent workspaces use <workspace-name>.- Before
deploy: themodelinagent.mdmust be listed bymutagent helix models --json, and the Environment you name with--envmust exist (mutagent env list --json). runneeds Helix on your machine: see mutagent install.
mutagent agent check
Compile and validate an agent folder. It makes no network request and no model call, and runs no tool code.
Refused when
model is missing, when the frontmatter has an apiVersion, kind or metadata key,
or when a path is outside the agent folder, is a symlink, or is an import outside the allowed set.
The compiler needs Bun 1.3.14, on your PATH or named by MUTAGENT_BUN_BIN.
0 and "status": "valid", with the package digests. On a failure, the error has
a diagnostics list that names each file problem. Fix every one before you deploy.
mutagent agent pack
Write the package archive and print its digests.deploy compiles the folder itself, so you do not need to run pack before it.
mutagent agent deploy
Compile the folder, upload it as a revision, validate the revision, and activate it in the slot.
Deploy creates the agent named by
name in agent.md, or uses the existing agent with that slug.
New content becomes the next revision; unchanged content uses its existing revision. Before
activating, deploy checks that:
modelis in the workspace model list (mutagent helix models).- The Environment named by
--envexists. - Every secret in
harness.bindings.secretssetsrequired: false.requireddefaults totrue. - The sandbox provider can receive a package.
0. With --json, stdout holds one object with slug, revision, activated,
environment, activeRevision and operationId; the status card goes to stderr. Keep the slug and
revision, then run the agent with mutagent helix agent @<slug>.
If a deploy fails with a network error or a server error, the error’s recovery holds the
idempotencyKey to retry with, or an operationId to look up with
mutagent agent inspect --operation <operation-id> --json. Retry with the same key; a new key is a new
deploy.
mutagent agent activate
Make a revision the slot’s active revision. Use it to roll back to an earlier revision.activate runs the same checks as deploy: the model and the Environment are checked again. New runs
use the new active revision. A running session keeps the revision it started with. Activating a
revision of a retired slot enables the slot again. An archived managed agent is refused with 409
MANAGED_AGENT_ARCHIVED: deploy its agent.md again to bring it back.
mutagent agent list
List the workspace’s managed agents and each slot’s active revision.mutagent agent ls is the same
command.
mutagent agent inspect
Show an agent’s revisions, its slots with their active revisions, and the sessions started from it.mutagent agent retire
Disable a slot. The slot takes no new runs, and live sessions finish. A run addressed to a retired slot is refused with 409 before any sandbox starts. Retiring a retired slot succeeds and changes nothing. To enable the slot again, runmutagent agent activate.
Retiring stops an agent from running, so the command needs --force, like a delete. Without it, the
command refuses and changes nothing, with or without --json.
mutagent agent run
Compile an agent folder and run a task with the Helix binary on your machine.
The run needs Helix installed on your machine (
mutagent install helix puts it at
~/.mutagent/bin/helix; MUTAGENT_HELIX_BIN names another one) and the API key of the LLM provider
named in model, in your local Helix login or your environment variables. It runs in a temporary copy of the compiled package on
your machine, not in a sandbox. It creates no agent, revision or slot in the workspace.
Specs, activity and versions
An agent’s spec, its history and its spec versions are kept by the Factory, for managed agents and every other agent, skill or workflow you register there:
The old commands were removed. Each one now exits 1 with
UNKNOWN_COMMAND and names the command to
run instead.
When the agent folder carries an agentspec, its metadata.id must equal name in agent.md: the
agent’s slug and its Factory entry id are the same. deploy refuses a mismatch with SLUG_MISMATCH
before any request is sent. Ask the person which one to rename, then deploy again.
retire needs —force
mutagent agent retire follows the rule for commands that stop or delete something: it refuses
without --force, with or without --json.
If it fails
See CLI errors.