mutagent agent

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.

These commands work on agents written as an agent.md folder. check, pack and run work on your machine. deploy, activate, list, inspect, retire, spec, activity and versions 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:

deploy compiles 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.
activate makes another revision active. retire disables the slot.

Before you start

Install the CLI.
check, pack, deploy and run compile the folder on your machine with Bun 1.3.14, on your PATH or named by MUTAGENT_BUN_BIN.
check, pack and run need no sign-in. Every other command needs a sign-in and a selected workspace. A coding agent signs in with MUTAGENT_API_KEY=<key> mutagent login --json, then runs mutagent workspaces use <workspace-name>.
Before deploy: the model in agent.md must be listed by mutagent helix models --json, and the Environment you name with --env must exist (mutagent env list --json).
run and spec sync need Helix on your machine: see mutagent install.

A typical sequence for a coding agent:

mutagent agent check <agent-folder>/agent.md --json
mutagent agent deploy <agent-folder>/agent.md --env <environment> --json
mutagent helix agent @<agent-slug> --env <environment> -p "<task>"

mutagent agent check

Compile and validate an agent folder. It makes no network request and no model call, and runs no tool code.

mutagent agent check <agent.md>

Argument	What it is
`<agent.md>`	The path to the agent’s entry file, or to its folder. The file must be named `agent.md`.

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.

mutagent agent check invoice/agent.md --json

Success: exit code 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.

mutagent agent pack <agent.md> --output <archive>

Argument or flag	What it does
`<agent.md>`	The path to the agent’s entry file, or to its folder.
`--output <archive>`	Where to write the archive. It must be outside the agent folder.
`--force`	Replace a file that already exists at `--output`. Without it, an existing file is refused.

deploy compiles the folder itself, so you do not need to run pack before it.

mutagent agent pack invoice/agent.md --output invoice.tgz

mutagent agent deploy

Compile the folder, upload it as a revision, validate the revision, and activate it in the slot.

mutagent agent deploy <agent.md> [--env <name>] [--no-activate] [--idempotency-key <key>]

Argument or flag	What it does
`<agent.md>`	The path to the agent’s entry file, or to its folder.
`--env <name>`	Use the slot in this Environment. The Environment must exist in the workspace. Without it, the default slot is used.
`--no-activate`	Store the revision but do not activate it. `@<slug>:v<N>` and `@<slug>:latest` can run it; `@<slug>` still runs the previous active revision.
`--idempotency-key <key>`	A key of 8 to 128 characters that makes a retry safe. If a deploy fails without a clear answer, such as a network error or a server error, run it again with the same key: the server returns the first attempt’s outcome instead of deploying twice. A new key is a new deploy.

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:

model is in the workspace model list (mutagent helix models).
The Environment named by --env exists.
Every secret in harness.bindings.secrets sets required: false. required defaults to true.
The sandbox provider can receive a package.

A failed check is refused with 422, or 404 for a missing Environment. A refused deploy writes no agent, revision or slot. Your local model key is never uploaded. Running sessions keep the revision they started with.

mutagent agent deploy invoice/agent.md --env prod --json
mutagent agent deploy invoice/agent.md --env prod --no-activate --json

Success: exit code 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.

mutagent agent activate <slug> --revision v<N> [--env <name>] [--idempotency-key <key>]

Argument or flag	What it does
`<slug>`	The agent’s slug.
`--revision v<N>`	The revision to activate.
`--env <name>`	Use the slot in this Environment. Without it, the default slot is used.
`--idempotency-key <key>`	A key of 8 to 128 characters that makes a retry safe, as for `deploy`.

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 activate invoice-pricing --revision v2 --env prod

mutagent agent list

List the workspace’s managed agents and each slot’s active revision. mutagent agent ls is the same command.

mutagent agent list [--include-archived] [--limit <count>] [--cursor <cursor>]

Flag	What it does
`--limit <count>`	Agents per page, from 1 to 100. The default is 20.
`--cursor <cursor>`	The `nextCursor` value from the previous page, to read the next one.
`--include-archived`	Also list archived managed agents. Without it, archived agents are left out.

mutagent agent inspect

Show an agent’s revisions, its slots with their active revisions, and the sessions started from it.

mutagent agent inspect <slug> [--env <name>] [--limit <count>] [--cursor <cursor>]
mutagent agent inspect --operation <operation-id>

Argument or flag	What it does
`<slug>`	The agent’s slug.
`--env <name>`	Show only the slot in this Environment and its sessions. Without it, every slot and every session is listed.
`--limit <count>`	Revisions per page, from 1 to 100. The default is 20.
`--cursor <cursor>`	The revision `nextCursor` from the previous `inspect`, to read the next page.
`--operation <operation-id>`	Show the recorded outcome of one `deploy` or `activate` instead of an agent. `deploy` and `activate` print the operation ID. Pass a slug or `--operation`, not both.

mutagent agent inspect invoice-pricing --env prod

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, run mutagent 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 retire <slug> [--env <name>] --force

Argument or flag	What it does
`<slug>`	The agent’s slug.
`--env <name>`	Retire the slot in this Environment. Without it, the default slot is retired.
`-f, --force`	Required. Confirms the retire.

mutagent agent retire invoice-pricing --env prod --force

mutagent agent run

Compile an agent folder and run a task with the Helix binary on your machine.

mutagent agent run <agent.md> "<task>"

Argument	What it is
`<agent.md>`	The path to the agent’s entry file, or to its folder. A slug is refused with the message “use `mutagent helix agent @slug`”.
`<task>`	The task to run.

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.

mutagent agent run invoice/agent.md "Price three widget units."

Spec sync, activity and versions

Keep the agent’s spec in step with your repository

An agent’s spec is the agentspec.yaml that Helix writes in its Spec stage: what the agent must do and the criteria it is judged by. A managed agent carries its spec in each revision. Your repository keeps its own copy. These commands compare the two and copy yours to the platform:

mutagent agent spec diff invoice-pricing agents/invoice/agentspec.yaml
mutagent agent spec sync invoice-pricing agents/invoice/agentspec.yaml
mutagent agent activate invoice-pricing --revision v4

Command	What it does
`agent spec get <slug> [--revision v<N>] [--out <file>]`	Show a revision’s spec. Without `--revision`: the active revision, else the newest. `--out` saves the raw file; replacing an existing file needs `--force`.
`agent spec diff <slug> <path>`	Show the lines that differ between your file and the newest revision’s spec (active or not), and whether they are in step. Changes nothing.
`agent spec sync <slug> <path>`	Check your file, then store it as a new revision. The new revision is not active until you run `agent activate`.
`agent spec sync-state <slug>`	Show what the last sync recorded, without reading a local file: `synced_as_of`, `platform_newer` or `unlinked`.

diff reports one of these states:

State	Meaning
`in-sync`	Your file and the platform’s spec are the same.
`ahead`	Your file is newer. `sync` it.
`behind`	The platform’s spec is newer. `spec get --out` fetches it.
`diverged`	Both changed since the last sync. Decide which one wins; it is never resolved for you.
`unlinked`	The agent was never synced.

sync checks the file with helix-cli, the spec validator that ships inside Helix, so Helix must be installed (mutagent install helix) with helix-cli on your PATH, or MUTAGENT_HELIX_CLI_BIN must name it. If the file has errors, sync lists every one and sends nothing. The check cannot be skipped. If the newest revision already carries the same spec, only the sync is recorded.

See what happened to an agent

mutagent agent activity invoice-pricing
mutagent agent versions invoice-pricing

activity lists what happened to the agent, newest first: created, spec changed, deployed, evaluated, diagnosed, optimized, or a report stored. Each row has the spec version and revision it concerns, who did it, and a reference to the operation or report. It pages with --limit (1 to 100, default 20) and --cursor. versions lists each spec version once, newest first, with the revision it arrived in and when it was first seen. The list is not paged.

retire needs —force

mutagent agent retire follows the rule for commands that stop or delete something: it refuses without --force, with or without --json.

mutagent agent retire invoice-pricing --env prod --force

If it fails

Exit code or error	Fix
`3` (`AUTH_REQUIRED`, `WORKSPACE_REQUIRED`)	Sign in, then `mutagent workspaces use <workspace-name>`.
`2` (`AUTH_EXPIRED`, `INVALID_API_KEY`)	Sign in again, or set a valid `MUTAGENT_API_KEY`.
`check` or `deploy` lists `diagnostics` (exit 1)	A file in the agent folder is wrong. Fix each diagnostic and run `check` again.
`deploy` or `activate` refused with 422 (exit 1)	The model is not in `mutagent helix models`, a secret binding is `required`, or no sandbox provider can receive the package. The message names which one.
`deploy` or `activate` refused with 404 (exit 1)	The `--env` Environment does not exist. Create it with mutagent env or fix the name.
`MANAGED_AGENT_ARCHIVED` (409, exit 1)	Deploy the agent’s `agent.md` again.
`activate` refused with 409 on the slot’s generation (exit 1)	The slot changed since you looked. Run `mutagent agent inspect <slug> --json`, then retry.
`AGENT_OUTPUT_EXISTS` (exit 1)	`pack --output` names a file that exists. Pass `--force` or choose another path.
`AGENT_LOCAL_START_FAILED` (exit 1)	`run` found no Helix. Run `mutagent install helix`, or set `MUTAGENT_HELIX_BIN`.
`AGENT_SPEC_INVALID` (exit 1)	`spec sync` found errors in the file and sent nothing. Fix each one in `errors`; do not retry the file unchanged.
`HELIX_CLI_NOT_FOUND` (exit 1)	`spec sync` needs `helix-cli`. Install Helix, put `helix-cli` on your `PATH`, or set `MUTAGENT_HELIX_CLI_BIN`.
`CONFIRMATION_REQUIRED` (exit 1)	`retire` needs `--force`. Confirm with the person first.

See CLI errors.

CLI

Account

Workspace

Helix

Setup

Before you start

mutagent agent check

mutagent agent pack

mutagent agent deploy

mutagent agent activate

mutagent agent list

mutagent agent inspect

mutagent agent retire

mutagent agent run

Spec sync, activity and versions

Keep the agent’s spec in step with your repository

See what happened to an agent

retire needs —force

If it fails

​Before you start

​mutagent agent check

​mutagent agent pack

​mutagent agent deploy

​mutagent agent activate

​mutagent agent list

​mutagent agent inspect

​mutagent agent retire

​mutagent agent run

​Spec sync, activity and versions

​Keep the agent’s spec in step with your repository

​See what happened to an agent

​retire needs —force

​If it fails

Before you start

mutagent agent check

mutagent agent pack

mutagent agent deploy

mutagent agent activate

mutagent agent list

mutagent agent inspect

mutagent agent retire

mutagent agent run

Spec sync, activity and versions

Keep the agent’s spec in step with your repository

See what happened to an agent

retire needs —force

If it fails