site/content/en/docs/guides/helm-agents-userguide.md
Since CVAT agents were announced, we have been working on making it easier for users to deploy their agents in CVAT and we are excited to share with you new ways to do that. In this guide we will cover how to deploy your agent to CVAT using Helm.
If you are familiar with Kubernetes and you want better control over your deployment and higher flexibility, you should go with Helm deployment instead of Docker compose.
In this guide we will cover the following topics:
values.yaml for your CVAT agentThe Helm chart automates the full lifecycle of a CVAT agent:
cvat-cli.
The resulting function ID is stored in a ConfigMap so the agent Deployment can pick it up.This means you don't need to run cvat-cli manually — the chart handles registration and deregistration for you.
To deploy CVAT agents with Helm, you need the following:
kubectl configured to talk to your clusterIf you plan to use GPU, make sure the NVIDIA device plugin is installed in your cluster and your
nodes have nvidia.com/gpu in .status.allocatable.
values.yaml for your CVAT agentClone the CVAT repository and navigate to the chart directory:
git clone [email protected]:cvat-ai/cvat.git
cd cvat/ai-models/agents_deployment/helm
Open values.yaml and configure the following sections.
Specify the Docker image that contains your agent implementation:
image:
repository: "cvat/sam2_agent"
tag: "latest"
pullPolicy: IfNotPresent
You can either build your own image or use one from the CVAT DockerHub
agent:
function_name: "myfunction" # Unique name for your function (unique per user)
replicaCount: 1 # Number of agent replicas
org_slug: "" # Organization slug (leave empty for personal scope)
use_cuda: false # Set to true if your image supports GPU
cvat_base_url: "https://app.cvat.ai" # URL of your CVAT instance
cvat_access_token: "" # Access token (NOT recommended — use secret_env instead)
Instead of putting the token in plain text, create a Kubernetes Secret and reference it:
kubectl -n cvat-agents create secret generic cvat-agent --from-literal=token=YOUR_TOKEN_HERE
Then in values.yaml:
agent:
cvat_access_token: "" # leave empty so the secret is used
secret_env:
- name: CVAT_ACCESS_TOKEN
secretName: cvat-agent
secretKey: token
Warning: If you set cvat_access_token directly, it will override secret_env
and the token will be visible in the Helm release history and pod specs.
The chart ships with presets for popular models. Pick a preset and optionally override parameters:
agent:
preset: sam2 # Available: yolo, sam2, transformers-detr, custom
# Override or add parameters on top of the preset:
modelParamsOverride: {}
# model_id:
# type: str
# value: "facebook/sam2.1-hiera-large"
agent:
resources:
limits:
cpu: 1
gpu: 1 # Only applied when use_cuda is true
requests:
cpu: 200m
gpu: 1 # Only applied when use_cuda is true
memory: 256Mi
When use_cuda: true, the gpu values are translated to nvidia.com/gpu resource requests/limits.
Use nodeSelector, affinity, and tolerations to control where agent pods are scheduled:
agent:
nodeSelector: {}
# nodetype: gpu
affinity: {}
tolerations: []
# - key: "nvidia.com/gpu"
# operator: "Exists"
# effect: "NoSchedule"
Mount additional volumes into agent containers if your model needs them:
agent:
extraVolumeMounts: []
# - name: model-cache
# mountPath: /models
extraVolumes: []
# - name: model-cache
# persistentVolumeClaim:
# claimName: model-cache-pvc
Once values.yaml is configured, deploy with:
helm install my-agent . -n cvat-agents --create-namespace
Helm will:
Check that the registration Job completed:
kubectl get jobs -n cvat-agents -l app.kubernetes.io/instance=my-agent
Check that agent pods are running:
kubectl get pods -n cvat-agents -l "app.kubernetes.io/instance=my-agent,app.kubernetes.io/component!=job"
View agent logs:
kubectl logs -n cvat-agents -l "app.kubernetes.io/instance=my-agent,app.kubernetes.io/component!=job" -f
Now go to CVAT UI and verify that the model is registered and available.
We will be running SAM2 tracker in this example, so I will draw a box around the object, then click on "Run annotation function"
So now we need to decide for how many frames we want to run the tracker. Let's say 14 frames.
We can see that the agent pod is processing the task:
So now we can see that the tracker has finished and the annotations are updated in CVAT:
To update the configuration (e.g. change replicas or model parameters):
helm upgrade my-agent . -n cvat-agents
The pre-upgrade hook will re-run the registration Job with the new parameters.
Simply uninstall the release:
helm uninstall my-agent -n cvat-agents
The pre-delete hook will automatically run a deregistration Job that removes the function from
CVAT before deleting all Kubernetes resources. No manual cvat-cli commands needed.
Check Job logs:
kubectl logs -n cvat-agents -l app.kubernetes.io/component=job
Common causes:
cvat_base_url — the cluster must be able to reach this URLcvat_access_token — generate a new one in CVAT UIfunction_name — must be unique per userkubectl describe pod -n cvat-agents -l app.kubernetes.io/name=agent
Common causes:
use_cuda: true but no GPU nodes available or NVIDIA device plugin not installednodeSelector / tolerations don't match any nodepreset and modelParamsOverride — make sure parameters are correct for your imageThe registration Job creates a ConfigMap <release>-config with the function ID. If something
goes wrong, you can inspect it:
kubectl get configmap -n cvat-agents -l app.kubernetes.io/instance=my-agent -o yaml
To start completely fresh, uninstall the release and reinstall:
helm uninstall my-agent -n cvat-agents
helm install my-agent ./chart -n cvat-agents