Deployment

This is the full deployment reference. The 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.

​

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