> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mutagent.io/llms.txt
> Use this file to discover all available pages before exploring further.

# mutagent agent

> Check, pack, deploy, activate, list, inspect, retire, and locally run agents written as an agent.md folder.

<Note>
  **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.
</Note>

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](/cli/commands/helix#mutagent-helix-agent). See [Managed agents](/helix/cloud/managed-agents)
for the `agent.md` format and a complete example.

How deployment works:

1. `deploy` compiles the folder and uploads it as a revision: `v1`, `v2`, and so on.
2. The revision becomes the active revision of a slot. A slot is one agent in one Environment;
   without `--env`, the default slot is used.
3. `mutagent helix agent @<slug>` runs the slot's active revision.
4. `activate` makes another revision active. `retire` disables the slot.

## Before you start

* [Install the CLI](/cli/installation).
* `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](/cli/commands/login)
  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](/cli/commands/install).

A typical sequence for a coding agent:

```bash theme={null}
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.

```bash theme={null}
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`.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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](/cli/commands/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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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. |

```bash theme={null}
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`.

```bash theme={null}
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. |

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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](/helix/lifecycle/spec):
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:

```bash theme={null}
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](/cli/commands/install)) 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

```bash theme={null}
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`.

```bash theme={null}
mutagent agent retire invoice-pricing --env prod --force
```

## If it fails

| Exit code or error | Fix |
| - | - |
| `3` (`AUTH_REQUIRED`, `WORKSPACE_REQUIRED`) | [Sign in](/cli/commands/login), 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](/cli/commands/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/errors).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.