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 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

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-alpha16 kagent version
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. 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
Kubernetes 1.37 and later serve the required APIs at certificates.k8s.io/v1 by default, so you do not need to change the API server configuration.
Confirm that the cluster serves the required APIs.
kubectl api-resources --api-group=certificates.k8s.io
Example output:
NAME SHORTNAMES APIVERSION NAMESPACED KIND certificatesigningrequests csr certificates.k8s.io/v1 false CertificateSigningRequest clustertrustbundles certificates.k8s.io/v1 false ClusterTrustBundle podcertificaterequests certificates.k8s.io/v1 true PodCertificateRequest

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.

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
```
Save a CLI configuration file that points the installer at those values. kagent install does not take 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
```
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.
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

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-postgresql-856b475f59-n258n                2/2     Running   0          2m
kagent-tools-54959b659c-lfkrz                     1/1     Running   0          2m
kagent-ui-5fdb6fd85c-vzb2z                        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 Agent, AgentTemplate, Session, 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']}"
To use this address with the kagent CLI, pass it in the --api-url flag.
kagent agent list --api-url http://<address>:8083
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.

Restrict kagent to specific namespaces

By default the controller watches every namespace, and the chart creates cluster-scoped RBAC (ClusterRoles and ClusterRoleBindings). To restrict kagent to a set of namespaces, set global.watchNamespaces in your Helm values:

global:
  watchNamespaces: [prod-agents, staging-agents]

Prefer global.watchNamespaces over the per-surface keys. The chart derives both surfaces from this one value, so they cannot disagree: it replaces every kagent ClusterRole with a Role and RoleBinding in each listed namespace, and it limits the controller’s watch to the same list. The chart appends the install namespace to the list automatically, so the release’s own objects remain managed.

The per-surface keys still exist for installs that scope the surfaces independently, and the validation rules bind them:

rbac.namespaces takes precedence over global.watchNamespaces whenever the key is present. An explicit rbac.namespaces: [] restores cluster-scoped RBAC. When rbac.namespaces is set, it must include the install namespace or the render fails.
config.kubernetes.watchNamespaces is an explicit watch override. Under rbac.namespaces, a watch entry that names a namespace outside the RBAC scope fails the render, because the controller would loop on Forbidden errors at runtime. Under global.watchNamespaces, the chart folds the entries into the watch scope instead of failing. In both cases the watch list replaces the default, so the install namespace is not added back once config.kubernetes.watchNamespaces is set — list it explicitly if the controller should keep watching it.
The kagent-tool-server RemoteMCPServer that the chart creates admits references from its own namespace only. An Agent in another watched namespace that binds it does not become ready until you set allowedNamespaces on that server. See Reach kagent-tool-server from another namespace.

Verify a namespaced install the same way as the default one, plus the negative case. The create your first agent guide’s kubectl get agents and conditions checks apply to each namespace; the difference is that an Agent the controller does not watch stays UNKNOWN forever.

Create one Agent in each watched namespace.

kubectl apply -n prod-agents -f my-agent.yaml
kubectl apply -n staging-agents -f my-agent.yaml

Create one Agent in a namespace the list does not cover.
```
kubectl apply -n dev-agents -f my-agent.yaml
```

Confirm that the controller reconciles the watched Agents.

kubectl get agents -n prod-agents
kubectl get agents -n staging-agents

Example output:

NAME           AGE   READY
my-agent       30s   True
my-agent       30s   True

Confirm that the Agent in the unwatched namespace stays unmanaged: its READY value stays UNKNOWN, and its conditions stay empty, because the controller has no watch entry for that namespace.
```
kubectl get agents -n dev-agents
kubectl get agent my-agent -n dev-agents -o jsonpath='{.status.conditions}'
```
Example output:
```
NAME           AGE   READY
my-agent       30s   UNKNOWN
null
```

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