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 labelledagent-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.
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 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.- 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.
- 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.
- 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.
- 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.
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.
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 labelagentops.komodor.io/revision-of=<agent>, so devops can
list them:
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
Scale agents to zero
Run no replica while an agent is idle.
Adopt agents installed with Helm
Let KAOP manage agents you already run from a Helm release.