Skip to content
This documentation covers the kagent 1.0 alpha. For the latest 0.x release, see the 0.x docs.

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

Install kagent

Page as Markdown
Install kagent 1.0 and Agent Substrate on a Kubernetes cluster.
kagent 1.0 runs every agent on Agent Substrate, so an installation sets up two systems in the same cluster. Agent Substrate provides the sandboxed compute that agents run on, and kagent provides the Harness, AgentTemplate, and Agent API that you author against. The kagent install command installs kagent, Agent Substrate, and the development PostgreSQL database together.
Note
These steps install kagent 1.0 fresh. kagent 1.0 has no in-place upgrade from the 0.10.x version line, and installing its custom resource definitions replaces the ones that a 0.10.x installation uses. To move an existing installation, start with Upgrade from 0.x.
Before you begin

  1. Install the following CLI tools.
    • helm, the Kubernetes package manager. Use Helm 3.
    • kubectl, the Kubernetes command line tool.
    • The kagent CLI, matched to the release that these docs cover.
      curl https://raw.githubusercontent.com/kagent-dev/kagent/refs/heads/main/scripts/get-kagent | bash -s -- --version v1.0.0-alpha13
kagent version
  2. Set your model provider API key. The examples in this guide use OpenAI. For other providers, see Configure model providers.
    export OPENAI_API_KEY="your-api-key-here"
  3. Prepare a Kubernetes cluster at 1.37 or later. Agent Substrate depends on the PodCertificateRequest and ClusterTrustBundle APIs. Both are generally available (GA) in 1.37 and served at certificates.k8s.io/v1 by default.
    For local testing and development, create a kind cluster at Kubernetes 1.37 or later. Use kind v0.32.0 or later. No extra API configuration is needed.
    kind create cluster --name kagent --image kindest/node:v1.37.0
Install kagent

The kagent CLI installs the CRDs, Agent Substrate, the Agent Substrate PodCertificate controller, a development PostgreSQL database, and kagent in the correct order. It also creates the Substrate identity material and database connection Secrets that the releases need.
  1. Save a Helm values file that enables gRPC server reflection, so that guides that use grpcurl can discover the controller API.
    cat > kagent-values.yaml <<EOF
config:
  server:
    grpcReflection: true
EOF
  2. Save a CLI configuration file that points the installer at those values. kagent install takes no Helm flags of its own, so chart values reach it through this file. A relative path in valuesFiles resolves against the configuration file’s own directory.
    cat > kagent-config.yaml <<EOF
install:
  kagent:
    valuesFiles: [kagent-values.yaml]
EOF
  3. Install kagent.
    kagent --config kagent-config.yaml install --namespace kagent
    The command reads your provider API key, installs Agent Substrate into ate-system, and deploys PostgreSQL as kagent-postgresql in the kagent namespace. It then connects kagent and Agent Substrate to that database with Pod Certificates. The development database runs the stock postgres image, which omits the pgvector extension that long-term memory needs.
  4. Wait for the controller to roll out.
    kubectl rollout status deployment/kagent-controller -n kagent --timeout=300s
    For production database requirements and direct Helm installation, see Operational considerations.
Verify the installation

  1. Confirm that the kagent pods are running.
    kubectl get pods -n kagent
    Example output:
    NAME                                              READY   STATUS    RESTARTS   AGE
kagent-controller-56c67b6cd7-hqj5z                1/1     Running   3          2m
kagent-default-774d4496bd-sfx4b                   1/1     Running   0          2m
kagent-grafana-mcp-7c67f5697c-4mf78               1/1     Running   0          2m
kagent-kmcp-controller-manager-6676b45958-zcvrp   1/1     Running   0          2m
kagent-postgresql-856b475f59-n258n                1/1     Running   0          2m
kagent-tools-54959b659c-lfkrz                     1/1     Running   0          2m
kagent-ui-5fdb6fd85c-vzb2z                        1/1     Running   0          2m

  2. Confirm that the WorkerPool reports a ready replica.
    kubectl get workerpools -n kagent
    Example output:
    NAME             DESIRED   REPLICAS   READY   AGE
kagent-default   1         1          1       2m

  3. Get the address to reach the kagent gRPC API, which serves the Session lifecycle and conversation calls. The guide to create your first agent assumes port-forwarding.
    Forward the controller port and leave the command running. The API is then available at localhost:8083.
    kubectl port-forward -n kagent svc/kagent-controller 8083:8083
  4. Optional: Open the kagent UI. The UI is a separate kagent-ui service, so it needs its own port-forward in a second terminal. The dashboard is then available at http://localhost:8082. For the kagent dashboard shortcut and a tour of the UI, see Launch the UI.
    kubectl port-forward -n kagent svc/kagent-ui 8082:8080
    To serve the UI behind a reverse proxy under a prefix such as /ui (configurable with ui.basePath), see Serve the UI under a sub-path.
Next steps

Your first agentApply a Harness, an AgentTemplate, and an Agent, then start a conversation with it.
Configure model providersPoint kagent at OpenAI, Anthropic, Gemini, or a provider of your own.
Operational considerationsReplace the evaluation defaults for the database, controller replicas, and Worker node pools.
Rotate the model provider API keyChange the API key in the kagent-openai Secret, which Helm owns, without breaking running agents.
Serve the UI under a sub-path