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

# Install koperator on a deploy target

> Create a deploy target in KAOP and install koperator in your cluster with one Helm command.

You install koperator once per deploy target. The Komodor Agentic Operation Platform (KAOP) gives
you the command; you run it on the cluster. For what koperator is, see
[Koperator](https://docs.komodor.com/manage-your-agents/build/koperator/overview).

## Before you start

* A Kubernetes cluster, and Helm 3 or later on the machine you install from.
* The namespaces that koperator will manage. Koperator never creates a namespace.
* For agents that scale to zero, KEDA 2.10 or later. If the cluster has no KEDA, koperator can
  install it (see [KEDA](https://docs.komodor.com/manage-your-agents/build/koperator/configure.md#keda)).
* Outbound access to the hosts in [Network
  requirements](https://docs.komodor.com/manage-your-agents/build/koperator/configure.md#network-requirements).

## Install

**1. Create the deploy target in KAOP**

In **Settings → Deploy targets**, choose **Create deploy target**. Give it a name and a
description, the namespaces it manages (**Specific namespaces** or **All namespaces**), the
namespaces it never manages, labels such as `env` and `team` for label-scoped grants, whether to
**Install KEDA with koperator**, and its guardrails. KAOP then opens the deploy target page with
the install command, which holds the install key.

The key is shown **once**. Copy the whole command before you choose **Hide the key** or leave
the page. After that, the page shows the command with a placeholder where the key goes.

**2. Run the install command**

Run the command on the cluster. It has three steps:

```sh theme={null}
kubectl create namespace agentops
kubectl -n agentops create secret generic koperator-<name>-credential --from-literal=key=<install key>
helm upgrade --install koperator-<name> oci://ghcr.io/komodorio/charts/koperator \
  --namespace agentops \
  --set-string controlPlane.url=https://agentops.komodor.com \
  --set-string credential.existingSecret=koperator-<name>-credential \
  --set-json 'namespaces=["team-a","team-b"]'
```

`<name>` is the deploy target's name in lower case, with each run of other characters than
letters and digits changed to `-`. The deploy target page shows the exact release name. KAOP adds `deniedNamespaces`, `guardrails`
and `keda.enabled` to the command when they apply, and `--version` when your KAOP control plane
names a chart version. The first line fails when the `agentops`
namespace already exists, for example when a second koperator runs on the cluster. That is
expected: run the next two lines.

The chart never takes the install key as a value, because a value goes into your shell history,
your CI logs and the stored Helm release. It reads the key from the Secret.

**3. Check the connection**

The deploy target shows **Connected** and the koperator version after the first heartbeat,
within about 30 seconds. If it does not, see [Troubleshooting](#troubleshooting).

## Rotate the install key

On the deploy target page, **Rotate key** returns the new key and a command that replaces it in the
cluster's Secret. Koperator reads the mounted key again before each call, so it needs no restart.
The old key keeps working until koperator first uses the new one, or for 24 hours. **Revoke now**
stops every key at once, and koperator stays disconnected until you install a new key: after a
revoke, **Issue a new key** gives one, with its command. Running agents keep serving while koperator
is disconnected.

## Troubleshooting

| You see | Do this |
| - | - |
| The deploy target stays **Disconnected** | Read the log of the leader replica (see below). A `401` or `403` means the key in the Secret is wrong or revoked. A timeout means the egress or the proxy blocks `agentops.komodor.com`. |
| `namespace "team-b" is already managed by koperator release ...` | Another koperator holds that namespace. Uninstall it, or take the namespace over with `forceClaim` (see [Namespace modes](https://docs.komodor.com/manage-your-agents/build/koperator/configure.md#namespace-modes)). |
| The install fails in the claim hook | Read `kubectl -n agentops logs job/koperator-<name>-claim`. It names the holder of each claim. |
| Creating the deploy target fails with `the name … gives Helm release …, which deploy target … already uses` | Two names give the same release name, for example `Prod 1` and `prod-1`. Choose another name. |
| A deploy fails with `guardrail_refused` | The message names the field and the guardrail. Change the spec in KAOP, or change the guardrail with `helm upgrade` (see [Guardrails](https://docs.komodor.com/manage-your-agents/build/koperator/configure.md#guardrails)). |

Koperator runs two replicas, and only the leader calls KAOP and changes agents. To read the right
log, find the leader first. The lease holder starts with the leader's pod name, before the `_`:

```sh theme={null}
kubectl -n agentops get lease koperator-<name> -o jsonpath='{.spec.holderIdentity}'
kubectl -n agentops logs <leader pod>
```

For a support case, collect a support bundle from the leader. It holds no secret values:

```sh theme={null}
kubectl -n agentops exec <leader pod> -- /koperator support-bundle > bundle.tgz
```

## Next steps

> [card] [Configure koperator](https://docs.komodor.com/manage-your-agents/build/koperator/configure.md)
>
> Namespaces, guardrails, Secrets, network, proxy and KEDA.

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

- [Koperator](https://docs.komodor.com/manage-your-agents/build/koperator/overview.md)
- [Upgrade koperator](https://docs.komodor.com/manage-your-agents/build/koperator/upgrade.md)
- [Uninstall koperator](https://docs.komodor.com/manage-your-agents/build/koperator/uninstall.md)
- [Configure koperator](https://docs.komodor.com/manage-your-agents/build/koperator/configure.md)
- [Deploy agents to a deploy target](https://docs.komodor.com/manage-your-agents/build/koperator/deploy-agents.md)


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