For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Learn how to install kagent

This guide covers ways to install and configure kagent in your Kubernetes environment. For a quick setup, see the Quick Start Guide. For enterprise offerings, see Solo Enterprise for kagent.

Installation Methods

Install kagent by using the kagent CLI or Helm.

Note: As of version 0.7, the kmcp subproject is included by default with kagent. To use an existing kmcp installation that you already set up separately, set kmcp.enabled=false in your values.yaml file or --set commands for both the kagent and kagent-crds charts.

Using kagent CLI (Recommended)

1. Set the OpenAI API key as an environment variable.

   export OPENAI_API_KEY="your-api-key-here"

2. Download the kagent CLI. By default, the latest version 0.9.9 of kagent is installed.

   brew install kagent

   or

   curl https://raw.githubusercontent.com/kagent-dev/kagent/refs/heads/main/scripts/get-kagent | bash

3. Install kagent to the cluster by using the CLI. The following command installs a demo profile with agents and MCP tools preloaded for you. If you don’t want these default agents, include the --profile minimal flag.

   kagent install --profile demo

   kagent installed successfully
   

4. Optional: Open the kagent dashboard.

   kagent dashboard

   Example output:

   kagent dashboard is available at http://localhost:8082
   Press Enter to stop the port-forward...
   

Using Helm

Another way to install kagent is using Helm.

1. Install the kagent Helm chart with CRDs.

   helm install kagent-crds oci://ghcr.io/kagent-dev/kagent/helm/kagent-crds \
       --namespace kagent \
       --create-namespace

2. Optionally prepare a Helm values file or --set flags to use for your installation. For example, you might set up your default LLM provider, or configure resource requests and limits or disable the default agents. For options, refer to the Helm reference docs.

Advanced Configuration

Review the following advanced configuration options that you might want to set up for your kagent installation.

Enable AgentHarness support

AgentHarness resources run on Agent Substrate. To enable them, install Agent Substrate and turn on the substrate integration in kagent. When the integration is disabled, the controller cannot provision AgentHarness resources.

1. Install Agent Substrate (CRDs, then the control plane and data plane).

   helm upgrade --install substrate-crds \
     oci://ghcr.io/kagent-dev/substrate/helm/substrate-crds \
     --namespace ate-system --create-namespace --wait
   
   helm upgrade --install substrate \
     oci://ghcr.io/kagent-dev/substrate/helm/substrate \
     --namespace ate-system --wait --timeout 10m

2. Install (or upgrade) kagent with the substrate integration and a WorkerPool enabled.

   Helm values file:

   controller:
     substrate:
       enabled: true
       ateApiEndpoint: dns:///api.ate-system.svc:443
       ateApiInsecure: true
   substrateWorkerPool:
     create: true
     replicas: 1

   Helm --set flags:

   helm upgrade --install kagent oci://ghcr.io/kagent-dev/kagent/helm/kagent \
   --namespace kagent \
   --set controller.substrate.enabled=true \
   --set controller.substrate.ateApiEndpoint=dns:///api.ate-system.svc:443 \
   --set controller.substrate.ateApiInsecure=true \
   --set substrateWorkerPool.create=true \
   --set substrateWorkerPool.replicas=1

   Pin the kagent chart to v0.9.9 or later. Earlier versions do not include the controller.substrate.* and substrateWorkerPool.* values.

For an end-to-end walkthrough on a kind cluster, see the Agent Substrate example. For more information about creating harness resources, see Agent Harness.

Database configuration

For production environments, set up kagent with an external PostgreSQL instance. For more information, see the Database configuration guide.

Configure controller environment variables

You can configure the controller by using environment variables for settings such as service names, connection details, and more.

Configure the controller service name

By default, kagent uses kagent-controller as the controller service name when constructing URLs for agent deployments. If you need to customize this name, set the KAGENT_CONTROLLER_NAME environment variable on the controller pod.

Helm --set flag:

helm install kagent oci://ghcr.io/kagent-dev/kagent/helm/kagent \
    --namespace kagent \
    --set controller.env[0].name=KAGENT_CONTROLLER_NAME \
    --set controller.env[0].value=my-kagent

Helm values file:

controller:
  env:
    - name: KAGENT_CONTROLLER_NAME
      value: my-kagent

More environment variables

You can add custom environment variables to the controller by using the controller.env field.

Helm --set flag:

helm install kagent oci://ghcr.io/kagent-dev/kagent/helm/kagent \
    --namespace kagent \
    --set controller.env[0].name=KAGENT_CONTROLLER_NAME \
    --set controller.env[0].value=my-kagent \
    --set controller.env[1].name=LOG_LEVEL \
    --set controller.env[1].value=debug

Helm values file:

controller:
  env:
    - name: KAGENT_CONTROLLER_NAME
      value: my-kagent
    - name: LOG_LEVEL
      value: debug
    - name: CUSTOM_VAR
      value: custom-value

Using secrets for environment variables

You can also reference Kubernetes secrets for environment variables by using the envFrom field in Helm.

controller:
  envFrom:
    - secretRef:
        name: controller-secrets

This example loads all key-value pairs from the controller-secrets secret as environment variables in the controller pod.

Customize Kubernetes resources

Use the following Helm values to meet cluster admission policies or integrate with external tooling.

Pod labels

Add labels to the pod templates of the controller and UI Deployments. Pod labels can be useful for clusters with policies (OPA Gatekeeper, Kyverno) that require specific labels on every pod.

A global podLabels map applies to all component pods; per-component values override it:

podLabels:
  team: platform

controller:
  podLabels:
    cost-center: infra

ui:
  podLabels:
    cost-center: frontend

To add labels to all agent pods, use controller.agentDeployment.podLabels.

ServiceAccount annotations

Add annotations to the controller and UI ServiceAccount resources. These annotations are required for cloud provider workload identity integrations (GCP Workload Identity, AWS IRSA, Azure Workload Identity) that grant IAM permissions to workloads by annotating their Kubernetes ServiceAccount.

controller:
  serviceAccount:
    annotations:
      iam.gke.io/gcp-service-account: kagent@my-project.iam.gserviceaccount.com

ui:
  serviceAccount:
    annotations:
      iam.gke.io/gcp-service-account: kagent-ui@my-project.iam.gserviceaccount.com

Deployment annotations

Add annotations to the controller and UI Deployment resources. For example, to add annotations for cluster autoscaler or Datadog:

controller:
  annotations:
    cluster-autoscaler.kubernetes.io/safe-to-evict: "false"

ui:
  annotations:
    cluster-autoscaler.kubernetes.io/safe-to-evict: "false"

To add annotations to the controller Service (for AWS Load Balancer Controller or ExternalDNS), use controller.service.annotations.

Default nodeSelector for agent deployments

Set a default nodeSelector that is applied to every agent Deployment that the controller creates. This setting can be useful when admission policies require a nodeSelector on all Deployments, since agents created through the UI carry none by default.

controller:
  agentDeployment:
    nodeSelector:
      kubernetes.io/os: linux

Per-agent nodeSelector values in the Agent spec take precedence over this default.

Affinity and topology spread constraints

Use affinity and topologySpreadConstraints to control pod scheduling for the controller and UI Deployments. Both fields accept standard Kubernetes scheduling objects.

controller:
  affinity:
    podAntiAffinity:
      preferredDuringSchedulingIgnoredDuringExecution:
        - weight: 100
          podAffinityTerm:
            labelSelector:
              matchLabels:
                app.kubernetes.io/component: controller
            topologyKey: kubernetes.io/hostname
  topologySpreadConstraints:
    - maxSkew: 1
      topologyKey: topology.kubernetes.io/zone
      whenUnsatisfiable: DoNotSchedule
      labelSelector:
        matchLabels:
          app.kubernetes.io/component: controller

ui:
  affinity: {}
  topologySpreadConstraints: []

When unset, no affinity or spread constraints are applied.

Deploy companion resources with extraObjects

Use extraObjects to deploy arbitrary Kubernetes manifests in the same Helm chart lifecycle as kagent. Entries are rendered through tpl, so they can reference the release context.

extraObjects:
  - apiVersion: external-secrets.io/v1beta1
    kind: ExternalSecret
    metadata:
      name: kagent-api-key
      namespace: "{{ .Release.Namespace }}"
    spec:
      refreshInterval: 1h
      secretStoreRef:
        name: my-store
        kind: ClusterSecretStore
      target:
        name: kagent-api-key
      data:
        - secretKey: ANTHROPIC_API_KEY
          remoteRef:
            key: anthropic-api-key

Disable the default ModelConfig

By default, kagent creates a ModelConfig resource and associated Kubernetes Secret for the provider that you set with providers.default. To skip this and manage ModelConfig resources entirely outside the Helm chart, set providers to null:

providers: null

When providers is null (or omitted), kagent does not create the ModelConfig or its Secret. Use this setting when you apply ModelConfig resources through GitOps, a separate Helm chart, or another external process.

Private registry and image mirroring

If your cluster cannot pull from ghcr.io directly, such as in air-gapped environments, corporate proxies, or mandatory image scanning, you can mirror the kagent images to an internal registry and configure the chart to pull from this registry.

kagent uses three independently configurable image locations:

To redirect all images to an internal mirror, set image.registry to your registry and override both agent images:

image:
  registry: my-registry.example.com

controller:
  agentImage:
    registry: my-registry.example.com
    repository: kagent/app
    tag: v0.10.0
  goAgentImage:
    registry: my-registry.example.com
    repository: kagent/golang-adk
    tag: v0.10.0

When unset, the registry and pullPolicy fields of agentImage and goAgentImage default to the global image.registry and image.pullPolicy values. For many mirror setups, setting only image.registry and overriding repository and tag on each image is sufficient.

Note: If you set only agentImage without also setting controller.goAgentImage, Go declarative agents still try to pull the Go ADK image from its default location, ghcr.io. The controller logs a startup warning when the two image registries differ.

Uninstallation

Refer to the Uninstall guide.

Next Steps

• Create your first agent
• Explore available agents