Installing kagent#

This guide covers ways to install and configure kagent in your Kubernetes environment. For a quick setup, check out our Quick Start Guide. For enterpise offerings, check out 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.

   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. Optionally: 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 require an OpenShell gateway that the kagent controller can reach. To enable the AgentHarness backends, install OpenShell and set OPENSHELL_GATEWAY_URL on the kagent controller deployment.

1. Install OpenShell in your cluster.

   kubectl create namespace openshell
   kubectl -n openshell create secret generic openshell-ssh-handshake \
       --from-literal=secret="$(openssl rand -hex 32)"
   
   kubectl apply -f https://raw.githubusercontent.com/NVIDIA/OpenShell/refs/heads/main/deploy/kube/manifests/agent-sandbox.yaml
   
   helm upgrade --install openshell oci://ghcr.io/nvidia/openshell/helm-chart \
   --version 0.0.49 \
   --namespace openshell \
   --create-namespace \
   --values - <<'EOF'
   server:
   disableTls: true
   auth:
      allowUnauthenticatedUsers: true
   service:
   metricsPort: 0
   EOF
   
   This example disables TLS and authentication. For production environments, configure TLS and authentication according to your OpenShell requirements.

2. Configure the kagent controller with the OpenShell gateway URL.

   Helm values file:

   controller:
     openshell:
         enabled: "true"
     env:
       - name: OPENSHELL_GATEWAY_URL
         value: dns:///openshell.openshell.svc:8080
       - name: OPENSHELL_INSECURE
         value: "true"

   Helm --set flags:

   helm upgrade --install kagent oci://ghcr.io/kagent-dev/kagent/helm/kagent \
   --namespace kagent \
   --set controller.openshell.enabled=true \
   --set 'controller.env[0].name=OPENSHELL_GATEWAY_URL' \
   --set-string 'controller.env[0].value=dns:///openshell.openshell.svc:8080' \
   --set 'controller.env[1].name=OPENSHELL_INSECURE' \
   --set-string 'controller.env[1].value=true'

   If you already configure controller.env, merge the OPENSHELL_GATEWAY_URL entry into your existing values. When OPENSHELL_GATEWAY_URL is empty, the controller does not register AgentHarness backends.

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.

Uninstallation#

Refer to the Uninstall guide.

Next Steps#

• Create your first agent
• Explore available agents