Skip to content

page.mdx

Latest commit

 

History

History
339 lines (242 loc) · 9.47 KB

page.mdx

File metadata and controls

339 lines (242 loc) · 9.47 KB
Raw
title Installing kagent
pageOrder 1
description Learn how to install kagent

export const metadata = { title: "Installing kagent", description: "Learn how to install kagent.", author: "kagent.dev" };

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.

3. Set the `OPENAI_API_KEY` environment variable: 
export OPENAI_API_KEY="your-api-key-here"

  1. Install the kagent Helm chart:

    helm install kagent oci://ghcr.io/kagent-dev/kagent/helm/kagent \
    --namespace kagent \
    --set providers.default=openAI \
    --set providers.openAI.apiKey=$OPENAI_API_KEY

  2. Optionally: Port-forward the kagent UI on port 8080.

    kubectl port-forward -n kagent svc/kagent-ui 8080:8080

  3. Open the kagent UI.

3. Set the `ANTHROPIC_API_KEY` environment variable: 
export ANTHROPIC_API_KEY="your-api-key-here"

  1. Install the kagent Helm chart:

    helm install kagent oci://ghcr.io/kagent-dev/kagent/helm/kagent \
    --namespace kagent \
    --set providers.default=anthropic \
    --set providers.anthropic.apiKey=$ANTHROPIC_API_KEY

  2. Optionally: Port-forward the kagent UI on port 8080.

    kubectl port-forward -n kagent svc/kagent-ui 8080:8080

  3. Open the kagent UI.

3. Set the `OPENAI_API_KEY` environment variable: 
export OPENAI_API_KEY="your-api-key-here"

  1. Install the kagent Helm chart:

    helm install kagent oci://ghcr.io/kagent-dev/kagent/helm/kagent \
    --namespace kagent \
    --set providers.default=azureOpenAI \
    --set providers.azureOpenAI.apiKey=$OPENAI_API_KEY

  2. Optionally: Port-forward the kagent UI on port 8080.

    kubectl port-forward -n kagent svc/kagent-ui 8080:8080

  3. Open the kagent UI.

3. Set the `GEMINI_API_KEY` environment variable: 
export GEMINI_API_KEY="your-api-key-here"

  1. Install the kagent Helm chart:

    helm install kagent oci://ghcr.io/kagent-dev/kagent/helm/kagent \
    --namespace kagent \
    --set providers.default=gemini \
    --set providers.gemini.apiKey=$GEMINI_API_KEY

  2. Optionally: Port-forward the kagent UI on port 8080.

    kubectl port-forward -n kagent svc/kagent-ui 8080:8080

  3. Open the kagent UI.

  1. Install the kagent Helm chart:

    helm install kagent oci://ghcr.io/kagent-dev/kagent/helm/kagent \
    --namespace kagent \
    --set providers.default=ollama

  2. Optionally: Port-forward the kagent UI on port 8080.

    kubectl port-forward -n kagent svc/kagent-ui 8080:8080

  3. Open the kagent UI.

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://github.com/kubernetes-sigs/agent-sandbox/releases/latest/download/manifest.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