> For the complete documentation index, see [llms.txt](https://docs.supervisely.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.supervisely.com/enterprise-edition/kubernetes/kubernetes-agent.md).

# Install the Kubernetes agent

This guide installs the Helm chart in **agent** mode (`mode: kubernetes-agent`). In this mode the chart does **not** install the Supervisely platform. Instead, it installs a lightweight agent that connects your cluster to an **existing** Supervisely instance and lets that instance run apps and tasks (including GPU workloads) on your cluster's nodes.

Use this when you already have a Supervisely instance and want to add a Kubernetes cluster as extra compute — for example, a dedicated GPU cluster.

{% hint style="info" %}
Not sure which mode you need? Read the [Overview](/agents/connect-your-computer/overview.md). If you want to run Supervisely itself on Kubernetes, use [Install full Supervisely](/enterprise-edition/kubernetes/installation.md) instead.
{% endhint %}

## How it works

The agent chart installs only the pieces needed to run tasks:

* A **task namespace** (a separate namespace where app/task pods run) with a network policy
* **RBAC** and a service account so Supervisely can create and manage task pods
* A one-time **registration job** that adds your cluster to the connected Supervisely instance as a compute node
* A **logs agent** that streams task logs back to the instance

Once installed, the cluster shows up as an available compute backend in your Supervisely instance, and you can launch apps on it.

## Before you start

* An existing, reachable Supervisely instance
* A Kubernetes cluster (version **1.21 or later**) with `kubectl` + `helm` (v3)
* Network connectivity **both ways**: the cluster must reach the Supervisely instance, and the instance must be able to reach the cluster to schedule work
* [NVIDIA device plugin](https://github.com/NVIDIA/k8s-device-plugin) on GPU nodes, if you want GPU tasks

## Step 1: Download the chart

The chart is the same one used for the full install — you just select agent mode in the values. Fetch it with the **Supervisely CLI** (the same `supervisely` command from the standard [installation](/enterprise-edition/get-supervisely/installation.md); set your license first with `supervisely set-license <YOUR_LICENSE>` if needed):

```bash
# latest version
supervisely k8s fetch-chart

# or a specific Supervisely version
supervisely k8s fetch-chart --version 6.12.3
```

The CLI downloads and unpacks the chart into `~/.supervisely/k8s/chart/` and prints the paths.

{% hint style="info" %}
Agent mode needs to be pointed at your existing instance, and the exact connection values depend on your setup. The easiest path is to ask Supervisely support to generate a ready-to-use agent `values.yaml` for your instance — then you only adjust storage and GPU settings below.
{% endhint %}

## Step 2: Configure your values

Set agent mode and point the agent at your instance:

```yaml
# Install the agent only, not the full platform.
mode: kubernetes-agent

options:
  # The address of your existing Supervisely instance,
  # reachable from this cluster.
  serverAddress: https://supervisely.mycompany.com

services:
  logsAggregator:
    taskExecution:
      # Where task logs are sent (your instance's public API URL).
      apiUrl: https://supervisely.mycompany.com
      token:
        # Shared token that authorizes this agent. Prefer an existing
        # secret in production; a plain value is shown here for clarity.
        value: "<TASK_EXECUTION_TOKEN>"
```

{% hint style="warning" %}
Agent mode requires the instance connection details (`serverAddress`, the logs `apiUrl` and `token`, and — depending on your deployment — access to the instance's database so the cluster can register itself). These are environment-specific. If in doubt, use the values file generated by Supervisely for your instance rather than filling them in by hand.
{% endhint %}

### Storage and GPU

* **Storage** — task pods may need scratch/persistent storage. Set a `storageClassName` as in the [full install guide](/enterprise-edition/kubernetes/installation.md#storage).
* **GPU** — to run GPU tasks, install the NVIDIA device plugin on GPU nodes and enable GPU pod presets under `nodeManager.node.options.podsPresets` (a preset with `supportsGpu: true` and `runtimeClassName: nvidia`). The generated `values.yaml` includes commented examples.

## Step 3: Install the chart

```bash
supervisely k8s install
```

This fetches the chart if needed and runs `helm upgrade -i` using your `values.yaml`, into the `supervisely` namespace. (You can also run `helm upgrade -i` directly against `~/.supervisely/k8s/chart` if you prefer.)

## Step 4: Verify

Check that the agent resources are up and the registration job completed:

```bash
kubectl -n supervisely get pods
kubectl -n supervisely get jobs
```

The registration job should show `Completed`, and the logs agent pod should be `Running`. Then open your Supervisely instance — the cluster should now appear as an available compute backend, ready to run apps and tasks.

## No cluster yet?

If you need to create a cluster first, there's a from-scratch tutorial for building one on AWS (cluster, storage, ingress, optional GPU nodes):

* [Build a cluster on AWS EKS](/enterprise-edition/kubernetes/aws-eks.md)