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

# Deploy agents to a deploy target

> Deploy, update, revise, stop and delete a self-hosted agent on a deploy target from KAOP, with no kubectl or helm of your own.

When devops has [installed koperator](https://docs.komodor.com/manage-your-agents/build/koperator/install.md) on a deploy
target, developers deploy and change self-hosted agents there from the Komodor Agentic Operation
Platform (KAOP). Koperator applies each change in the cluster, so nobody runs `kubectl` or `helm`.

## Deploy an agent

In the create wizard, on the **Where it runs** step, choose self-hosted. Under **How it gets to your
cluster**, choose **Deploy to a deploy target**, then pick the **Deploy target** and the
**Namespace**. The wizard offers only the deploy targets you may deploy to, and only the Secrets and
ServiceAccounts that devops labelled `agent-usable` there.

A catalog agent that needs cluster permissions or a cloud identity runs only as a ServiceAccount that
your cluster admin prepares. The wizard shows that ServiceAccount under **Your cluster admin prepares
the ServiceAccount**. The admin creates it and labels it `agentops.komodor.io/agent-usable=true`.

The agent's page then has a **Deployment** panel. It shows each change until koperator completes it,
or why koperator failed or refused it, for example `guardrail_refused`. If koperator is
disconnected, the change waits and the wizard says so.

An agent stays on the deploy target and the namespace you chose. To move it, delete it and deploy it
again.

## Update an agent

Open the agent's **Edit** wizard and choose **Save and update on** the deploy target. Koperator
applies the change. **Save only** keeps the changes for later: the **Deployment** panel then shows
them as not deployed, with **Deploy saved changes**.

When a change fails, the **Deployment** panel offers **Retry**, which applies the same spec again,
and **Revert to generation N**, which applies the spec of the previous generation. A revert also
restores the agent's saved configuration to that version. When revisions on a deploy target are
turned on for your account, a revert is a rollback, so it needs the permission to approve on that
deploy target.

## Change policy

Each deploy target has a **Change policy**, which an owner or admin sets on the deploy target page:

* **Direct edits** (the default): a change to a live agent deploys at once.
* **Revisions required**: a change to a live agent's image, prompt, model, skills, MCP servers, LLM,
  environment variables, ServiceAccount, pod annotations or pull Secrets is a revision. It runs
  beside the agent and must be approved. Scale, resources, placement, the first deploy, Stop, Resume,
  Archive, Delete and Adopt stay direct.

On a deploy target that requires revisions, the **Edit** wizard checks the change on **Review**. If
it changes one of those fields, it names them, and the button becomes **Save as revision**. KAOP
saves the configuration, creates a revision with those fields, applies the scale, resources and
placement changes at once, and opens the revision's page. Through the API, a direct change to one of
those fields fails with `revision_required`, and the message names the fields.

### Break-glass

For an urgent fix, a person who may approve on the deploy target can skip the revision. In the
**Edit** wizard, choose **Deploy anyway…**, type the reason, and confirm. The change deploys at once,
and the audit log records the reason and the fields. Use it only when there is no time for a
revision.

## Revisions on a deploy target

An [agent revision](https://docs.komodor.com/manage-your-agents/fleet/agent-page.md) of an agent on a deploy target runs
beside the agent, on the same deploy target and in the same namespace. Koperator deploys it, with
no manual step, and removes it when you discard it or approve it.

1. **Create the revision.** On the agent's **Revisions** tab, choose **Create revision**, or choose
   **Save as revision** in the **Edit** wizard. The last step shows the deploy target, the checks
   and the progress of the deploy. It shows no Helm command and no token.
2. **Test it.** When the revision is **Running**, turn on **Shadow** on its page. The revision then
   gets a copy of the agent's runs, and the agent still answers. You can also send it a share of the
   live traffic with **Manage traffic routing** on the agent's **Revisions** tab.
3. **Approve it.** **Approve** names the deploy target. After you confirm, koperator updates the
   agent to the revision's spec, and the dialog shows the steps. The agent keeps serving its
   current version until the new one is ready. When the update completes, the revision becomes
   main, its traffic stops, and koperator removes its objects. If the update fails, nothing moves:
   the revision stays open and running, and you can approve it again. While koperator has not
   received the update, **Cancel the promote** withdraws it.
4. **Roll back if needed.** **Roll back** on the approved revision's page sends the earlier spec to
   the agent the same way. Main moves back when the update completes.

While an approve is in progress, you cannot edit, discard or shadow that revision, or make it main.

### Permissions

Each action needs a permission on the agent and a permission on its deploy target. A grant on one
deploy target does not allow the action on another one.

| Action | Who can do it by default |
| - | - |
| Create, edit or discard a revision, and turn shadow on or off | Developer, owner, admin |
| Approve, roll back, make a revision main, cancel an approve, revert | Owner, admin |
| Break-glass edit | Owner, admin |
| Set the change policy of a deploy target | Owner, admin |

To let a team lead approve on staging only, give the approve permission on the deploy targets that
carry a staging label.

### From the assistant

The KAOP assistant can propose a revision, an approve or a rollback of an agent on a deploy target.
It does not make the change itself: it shows a card in the chat, and the change runs when you
confirm it, with your own permissions. It proposes it only if you have the permission on that
deploy target. It never makes a break-glass edit.

The objects of a revision carry the label `agentops.komodor.io/revision-of=<agent>`, so devops can
list them:

```sh theme={null}
kubectl -n <namespace> get deployments -l agentops.komodor.io/revision-of=<agent>
```

Revisions on a deploy target are turned on per account. If a revision of an agent on a deploy target
gives you a Helm command instead, ask your account team to turn it on.

## Stop, resume and delete

**Stop** lets the runs in progress finish, then stops the agent; **Stop now** cancels them. A stopped
agent takes no new work, also while koperator is disconnected, and koperator scales it to zero.
**Resume** starts it again. Stop and Stop now are turned on per account; if the agent page does not
offer them, ask your account team.

To remove an agent, archive it, then delete it. Koperator deletes the objects it applied, and KAOP
revokes the agent's worker token.

## Next steps

> [card] [Scale agents to zero](https://docs.komodor.com/manage-your-agents/build/scale-to-zero.md)
>
> Run no replica while an agent is idle.

> [card] [Adopt agents installed with Helm](https://docs.komodor.com/manage-your-agents/build/koperator/adopt-helm-agents.md)
>
> Let KAOP manage agents you already run from a Helm release.


## Related topics

- [Upgrade koperator](https://docs.komodor.com/manage-your-agents/build/koperator/upgrade.md)
- [Koperator](https://docs.komodor.com/manage-your-agents/build/koperator/overview.md)
- [Install koperator on a deploy target](https://docs.komodor.com/manage-your-agents/build/koperator/install.md)
- [Deploy a self-hosted agent](https://docs.komodor.com/manage-your-agents/build/deploy-a-self-hosted-agent.md)
- [Quickstart](https://docs.komodor.com/get-started/quickstart.md)


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