Install kagent

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 AgentInstance API that you author against. Install Agent Substrate first, because the kagent controller connects to it at startup.

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

Install the following CLI tools.
- helm, the Kubernetes package manager. Use Helm 3.
- kubectl, the Kubernetes command line tool.
- jq, to read the root certificate out of the generated CA pool.
- openssl, to convert that certificate to PEM format.
- kubectl-ate, the Agent Substrate command line tool, published as a kubectl plugin with each Agent Substrate release.
  curl -fsSL -o kubectl-ate \ "https://github.com/kagent-dev/substrate/releases/download/v0.2.0-beta4/kubectl-ate-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m | sed 's/x86_64/amd64/; s/aarch64/arm64/')" chmod +x kubectl-ate sudo mv kubectl-ate /usr/local/bin/ kubectl ate --help
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"
```
Prepare a Kubernetes cluster at 1.37 or later and enable it with the following requirements for Agent Substrate.
For local testing and development, create a kind cluster at Kubernetes 1.37 or later. Use kind v0.32.0 or later. Enable the certificates.k8s.io/v1beta1 API, which Agent Substrate depends on.
kind create cluster --image kindest/node:v1.37.0 --config=- <<EOF kind: Cluster apiVersion: kind.x-k8s.io/v1alpha4 name: kagent runtimeConfig: "certificates.k8s.io/v1beta1": "true" EOF
To use an existing Kubernetes 1.37 or later cluster, you must manually enable the certificates.k8s.io/v1beta1 API, which Agent Substrate depends on.
1. On each control plane node, add the runtime configuration to the kube-apiserver manifest. The kubelet restarts the static pod when the file changes, so no restart command is needed.
  # /etc/kubernetes/manifests/kube-apiserver.yaml spec: containers: - command: - kube-apiserver - --runtime-config=certificates.k8s.io/v1beta1=true
  Note
  If the command list already has a --runtime-config flag, edit that line instead of adding a second one. A duplicate flag is silently ignored, and the API is not served.
2. Confirm that the beta group is served. Be sure to check the served API versions, not the resource list.
  kubectl api-versions | grep certificates.k8s.io
  Example output:
  certificates.k8s.io/v1 certificates.k8s.io/v1beta1

Install Agent Substrate

Deploy the Agent Substrate control plane and data plane into the ate-system namespace, then create the identity material that its components authenticate with. Agent Substrate signs pod identities and service certificates from certificate authority (CA) pools that you generate, and it authenticates callers against a JSON Web Token (JWT) authority pool.

Important

Creating the identity material is required, and no Helm chart performs it for you. Agent Substrate authenticates its components with mutual Transport Layer Security (mTLS), and the identity material that mTLS depends on is created by the kubectl-ate plugin, not by Helm.

Install the Agent Substrate custom resource definitions (CRDs).

helm upgrade --install substrate-crds \
  oci://ghcr.io/kagent-dev/substrate/helm/substrate-crds \
  --version 0.2.0-beta4 \
  --namespace ate-system --create-namespace

Install the Agent Substrate control plane and data plane. Do not add --wait to this command, because the pods cannot become ready until you create the identity material in the following steps.
```
helm upgrade --install substrate \
  oci://ghcr.io/kagent-dev/substrate/helm/substrate \
  --version 0.2.0-beta4 \
  --namespace ate-system
```

Create the CA pools that sign service DNS and pod identity certificates.

kubectl ate admin make-ca-pool --ca-id=1 \
  --name=service-dns-ca-pool \
  --secret-namespace=podcertificate-controller-system
kubectl ate admin make-ca-pool --ca-id=1 \
  --name=pod-identity-ca-pool \
  --secret-namespace=podcertificate-controller-system

Create the actor identity pools that Agent Substrate uses to issue and verify actor credentials.

kubectl ate admin make-jwt-pool --key-id=1 \
  --name=actor-id-jwt-pool \
  --secret-namespace=ate-system
kubectl ate admin make-ca-pool --ca-id=1 \
  --name=actor-id-ca-pool \
  --secret-namespace=ate-system

Extract the actor identity root certificate and store it in the secret that the Agent Substrate API server reads.

actor_id_ca_root="$(kubectl get secret actor-id-ca-pool -n ate-system \
  -o jsonpath='{.data.pool}' | base64 --decode \
  | jq -r '.CAs[0].RootCertificateDER' | base64 --decode \
  | openssl x509 -inform der -outform pem)"

kubectl create secret generic actor-id-ca-certs -n ate-system \
  --from-literal=ca.crt="${actor_id_ca_root}"

Create the authentication configuration. The kubernetes provider accepts Kubernetes ServiceAccount tokens that are issued for the Agent Substrate API server audience.

kubectl create configmap ate-api-authentication -n ate-system \
  --from-literal=authentication.yaml='actorIdentityJWTProvider: kubernetes
jwtProviders:
- name: kubernetes
  issuer: https://kubernetes.default.svc
  audiences: [api.ate-system.svc]
  certificateAuthorityFile: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt
  discoveryTokenFile: /var/run/secrets/kubernetes.io/serviceaccount/token
'

Roll Agent Substrate out again so that its pods mount the identity material, and wait for them to become ready.

helm upgrade substrate \
  oci://ghcr.io/kagent-dev/substrate/helm/substrate \
  --version 0.2.0-beta4 \
  --namespace ate-system --reuse-values --wait --timeout 10m

Verify that Agent Substrate is running.

kubectl get pods -n ate-system

Example output:

NAME                              READY   STATUS      RESTARTS   AGE
ate-api-server-59fccdf6dc-f77h6   1/1     Running     3          9m
ate-api-server-59fccdf6dc-q49hv   1/1     Running     3          9m
ate-controller-6c788456f8-zh2rm   1/1     Running     0          9m
atelet-wxm5s                      1/1     Running     0          9m
atenet-egress-66f5699886-6rgg9    2/2     Running     0          9m
atenet-router-645bd98bdd-dlrv2    2/2     Running     0          9m
dns-6bf4fff5bb-zqsnm              2/2     Running     0          9m
postgres-0                        2/2     Running     0          9m
rustfs-56cdbc9dcb-2ntck           1/1     Running     0          9m
rustfs-bucket-init-4pxgt          0/1     Completed   0          9m

Install kagent

The kagent chart connects the controller to Agent Substrate and creates a WorkerPool for agents to run on. A WorkerPool is platform capacity that you provision once, and every Harness references it. No Harness can run until a WorkerPool exists. The values in the following steps are evaluation defaults, including a bundled PostgreSQL instance, one controller replica, and one Worker. For a production installation, add the production values from Operational considerations to the same command.

Important

Install kagent 1.0 with Helm. The kagent install command does not yet provision Agent Substrate and cannot produce a working 1.0 installation.

Install the kagent CRDs.

helm upgrade --install kagent-crds \
  oci://ghcr.io/kagent-dev/kagent/helm/kagent-crds \
  --version 1.0.0-alpha1 \
  --namespace kagent --create-namespace --wait

Install kagent with the Agent Substrate integration enabled.

helm upgrade --install kagent \
  oci://ghcr.io/kagent-dev/kagent/helm/kagent \
  --version 1.0.0-alpha1 \
  --namespace kagent --create-namespace --timeout 10m \
  -f - <<EOF
providers:
  default: openAI
  openAI:
    apiKey: ${OPENAI_API_KEY}
controller:
  grpc:
    reflection: true
  substrate:
    enabled: true
    ateApiEndpoint: dns:///api.ate-system.svc:443
    atenetRouterURL: http://atenet-router.ate-system.svc:80
    defaultWorkerPool:
      name: kagent-default
substrateWorkerPool:
  create: true
  replicas: 1
  workerImage: "ghcr.io/kagent-dev/substrate/ateom-gvisor:v0.2.0-beta4"
EOF

Note

controller.grpc.reflection lets a gRPC client discover the controller’s methods without a local copy of kagent’s proto files. The kagent CLI does not need it, because the CLI ships with generated clients for every kagent API. Leave reflection on to explore the API with a general-purpose client such as grpcurl, and turn it off for a production installation.

Wait for the controller to roll out.

kubectl rollout status deployment/kagent-controller -n kagent --timeout=300s

Note

The kagent controller can restart a few times during a first install while it waits for its bundled PostgreSQL database to accept connections. The controller logs dial tcp ...:5432: connect: connection refused and then recovers on its own. A restart loop that reports an ate-api dial failure instead indicates an incomplete identity bootstrap.

Verify the installation

Confirm that the kagent pods are running.

kubectl get pods -n kagent

Example output:

NAME                                              READY   STATUS    RESTARTS   AGE
kagent-controller-659b58768b-2k6h4                1/1     Running   3          2m
kagent-default-864fdc4c94-xbsl9                   1/1     Running   0          2m
kagent-kmcp-controller-manager-6676b45958-knkzd   1/1     Running   0          2m
kagent-postgresql-65cc684b78-9qbh2                1/1     Running   0          2m

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

Get the address to reach the kagent gRPC API, which serves the AgentInstance 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
Read the external address of the controller service. The gRPC API listens on port 8083.
kubectl get svc -n kagent kagent-controller \ -o jsonpath="{.status.loadBalancer.ingress[0]['hostname','ip']}"

Next steps

Your first agentApply a Harness and AgentTemplate, and talk to the AgentInstance they produce. 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.

Configure model providers