> ## 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.

# Deployment

> How a managed agent moves through deploy, activate, run, retire and archive, and what each step checks and refuses.

<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>

This is the full deployment reference. The [overview](/platform/managed-agents/overview) has the
essentials. A managed agent moves through these steps. Each step names a slot with `--env <name>`;
without `--env`, it uses the default slot, which has no Environment.

```mermaid theme={null}
flowchart LR
  D["Deploy"] --> A["Active revision in the slot"]
  A --> RUN["Run"]
  A --> RET["Retire the slot"]
  RET -- "activate" --> A
  RET -- "every slot retired, then delete" --> AR["Archived agent"]
  AR -- "deploy the same name" --> D
  classDef s fill:#140d22,stroke:#7E47D7,color:#ede7f8;
  class D,A,RUN,RET,AR s;
```

## Deploy

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

Deploy compiles the folder on your machine and uploads the package. Before anything is written, the
server verifies the package digests and its `name`, and checks:

* `model` is in the workspace model list (`mutagent helix models`). A model of an LLM provider the
  workspace has not configured is refused with 428.
* The Environment named by `--env` exists in the workspace.
* Every secret in `harness.bindings.secrets` sets `required: false`. `required` defaults to `true`.
* At least one sandbox provider can receive a package.
* No inline agent already uses the slug.

A refused deploy leaves nothing behind. A deploy that passes, in one step:

* Creates the agent by its `name`, or reuses the agent with that slug. An archived agent with that
  slug is brought back.
* Stores new content as the next revision, or reuses the revision with unchanged content.
* Creates the slot on the first deploy to it.
* Activates the revision in the slot. With `--no-activate`, the revision exists, but `@slug` still
  runs the previous active revision.

Deploy, activate and retire need a [sign-in](/cli/commands/login) with a workspace selected; without
one they exit 3. With `--json`, deploy prints one result on stdout: `slug`, `revision` (a number),
`activated`, `environment`, `activeRevision` and `operationId`. `status` is `active`, or `stored`
with `--no-activate`. A refusal exits 1 with the server's `code`, such as `MODEL_NOT_IN_LIST` or
`ENVIRONMENT_NOT_FOUND`.

If a deploy or activate fails without an answer (a network error or a 5xx), the request may still
have been accepted. Run the same command again with the `--idempotency-key` the error names; a new
key is a new request. `mutagent agent inspect --operation <operation-id> --json` shows the recorded
outcome of an operation.

## Activate

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

Activate makes revision N the slot's active revision. Use it to roll back to an earlier revision.

* It runs the same checks as deploy: the model, the Environment and the sandbox provider.
* Each slot has one active revision. Activating a revision replaces the previous one in that slot.
* A running session keeps the revision it started with. New runs use the new active revision.
* It enables a retired slot again.
* It refuses an archived agent with 409 `MANAGED_AGENT_ARCHIVED`. Only deploy brings an archived
  agent back.

## Run

`mutagent helix agent @<slug>[:v<N>|:latest] [--env <name>] -p "<task>"`

The address chooses the revision:

| Address | Runs |
| - | - |
| `@invoice-pricing` | The slot's active revision. |
| `@invoice-pricing:v3` | Revision 3, pinned, whether or not it is active. |
| `@invoice-pricing:latest` | The newest validated revision, active or not. |

Before any sandbox starts, the run is refused when:

* No agent has that slug (404).
* The agent has no slot in that Environment (404). Deploy to it first.
* The agent is archived (409 `MANAGED_AGENT_ARCHIVED`).
* The slot is retired (409 `MANAGED_AGENT_SLOT_RETIRED`), with a pinned revision or without.
* The slot has no active revision, `vN` does not exist or is not validated, or `:latest` finds no
  validated revision (422).
* The model is not in the workspace model list (422). If the LLM provider was deactivated after
  deploy, the run is refused.
* The slot's Environment no longer exists (404, naming the Environment). `mutagent agent inspect`
  still lists the slot.
* The chosen sandbox provider cannot receive a package (422).

With `-p`, a refusal is printed on stderr with the fix to run. In `--rpc` mode it is one JSON line on
stderr with `code`, `error` and `suggestedAction`; stdout stays the session's.

After these checks, the sandbox starts, the package is copied in and its digest is checked, and Helix
starts with the package's prompt, tools and skills. If the tools the package registers do not match
`agent.md`, the run stops and its sandbox is stopped.

## Retire

`mutagent agent retire <slug> [--env <name>] --force`

Retire disables the slot. The slot takes no new runs, and live sessions finish. To enable the slot
again, activate a revision in it.

`--force` (or `-f`) is required every time, `--json` included. Retiring a slot that is already
retired succeeds and changes nothing.

## Archive

The `mutagent` CLI has no delete command. Deleting a managed agent with the SDK (`agents.deleteAgent`
in TypeScript, `agents.delete_agent` in Python) archives it:

* While any slot is live, the delete is refused with 409 `MANAGED_AGENT_HAS_SLOTS`. Retire every slot
  first.
* Once every slot is retired, the agent is archived, not deleted. Its revisions and session history
  stay.
* `mutagent agent list` leaves archived agents out. `mutagent agent list --include-archived` shows
  them.
* Activate and run refuse an archived agent.
* Deploying the same `name` again brings the agent back.

## Not available yet

| Not available yet | What to do now |
| - | - |
| Restoring a managed agent's session. `session restore` refuses it with 409 `MANAGED_AGENT_RESTORE_UNSUPPORTED`. | Start a new run. A checkpoint of the session can still be saved and listed. |
| Receiving a package on every sandbox provider. | Run on a sandbox provider that deploy and run accept. |
| Adding declared secret bindings to the sandbox by name. | Set `required: false`, or leave secrets out of `harness.bindings`. Put the value in the slot's Environment; it is loaded into the sandbox on every run. |
| Permissions specific to deployments. | `mutagent agent` commands use your workspace sign-in. |

<CardGroup cols={2}>
  <Card title="Managed agents" icon="cloud" href="/platform/managed-agents/overview">
    The agent, its revisions, its slots, and its runs.
  </Card>

  <Card title="mutagent agent" icon="terminal" href="/cli/commands/agent">
    Every `mutagent agent` command and its flags.
  </Card>
</CardGroup>


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