Kubernetes

Deploy OpenAgentics into any Kubernetes cluster with the self-contained Helm chart.

OpenAgentics ships a self-contained Helm chart, hosted as a packaged .tgz at install.openagentics.io. The chart deploys the full platform — the application services and all stateful dependencies (PostgreSQL with pgvector, Redis, Ollama, and Milvus) — as plain Kubernetes Deployments. There are no external subcharts to install first, and a single helm install brings up the whole stack. The chart runs on any cluster: managed (GKE, EKS, AKS), on-premises, or k3s.

Note: For single-node or local evaluation, prefer Docker Compose.

Before you begin

You need the following before installing the chart:

The chart is self-contained. PostgreSQL (pgvector), Redis, Ollama, and Milvus all ship as in-chart Deployments, so you do not add any Helm repositories or install dependency charts separately.

Note: Milvus is enabled by default (milvus.enabled: true) and bundles its own etcd and MinIO pods inline. It backs the tool semantic cache. To run with pgvector only and skip the Milvus, etcd, and MinIO pods, set milvus.enabled: false in your values file.

Install

Follow these steps to install OpenAgentics into a namespace named openagentic.

1. Create the namespace.

   kubectl create namespace openagentic

2. (Optional) Create a TLS secret and an image pull secret. Create the TLS secret only if you terminate HTTPS in-cluster with an existing certificate. Create the pull secret only if you use a private registry; the default images are public (ghcr.io/agentic-work).

   kubectl create secret tls openagentic-tls \
     --cert=path/to/tls.crt --key=path/to/tls.key \
     -n openagentic
   
   kubectl create secret docker-registry registry-pull-secret \
     --docker-server=<your-registry-host> \
     --docker-username=<user> --docker-password=<token> \
     -n openagentic

3. Create a values file and install the chart. The stateful dependencies come up as part of this single install.

   helm upgrade --install openagentic https://install.openagentics.io/openagentic-1.0.0.tgz \
     --version 1.0.0 \
     -n openagentic \
     -f my-values.yaml

   Get the full set of configurable values straight from the chart, then edit a copy:

   helm show values https://install.openagentics.io/openagentic-1.0.0.tgz > my-values.yaml

   Fill in your provider, credentials, and (for air-gapped installs) image.registry / image.tag, then pass it with -f.

To upgrade an existing release, run helm upgrade again with the same values file:

helm upgrade openagentic https://install.openagentics.io/openagentic-1.0.0.tgz \
  --version 1.0.0 \
  -n openagentic \
  -f my-values.yaml

Important: Override secrets.* (Postgres password, jwtSecret, signingSecret, internalApiKey, frontendSecret, and the admin seed) in your own values file for any non-demo deployment. The defaults are development placeholders.

Verify the deployment

Confirm that the pods are running and the API is healthy.

kubectl get pods -n openagentic -o wide
kubectl rollout status deploy/api -n openagentic

The API Service is named api on port 8000, and the UI Service is named ui on port 80. Port-forward the API to check its health endpoint:

kubectl port-forward -n openagentic svc/api 8080:8000 &
curl -s http://localhost:8080/api/health | jq .

To reach the web UI without an Ingress, port-forward the UI Service and open http://localhost:8080:

kubectl port-forward -n openagentic svc/ui 8080:80

Troubleshoot common failures

Use these steps to diagnose the most frequent install problems.

Inspect logs and recent events while troubleshooting:

kubectl logs -n openagentic deploy/api --tail=100
kubectl get events -n openagentic --sort-by=.lastTimestamp

Point at your Ollama

The in-cluster Ollama always serves embeddings (nomic-embed-text is light and runs CPU-only). The chat model is served according to ollama.chatHost:

• Leave chatHost empty to serve chat from the in-cluster Ollama (the chatModel is pulled in-cluster).
• Set chatHost to a remote Ollama URL (for example, a GPU box) to serve large chat models there; the in-cluster Ollama then pulls only the embedding model.

ollama:
  embedModel: nomic-embed-text   # required for RAG and memory
  chatModel: llama3.2:3b         # pulled on first boot when chatHost is empty
  chatHost: ""                   # set to http://HOST:11434 for a remote chat Ollama
  gpu: false                     # set true only for a large in-cluster chat model

Reference deployment. Our own cluster runs exactly this shape — Raspberry Pi (ARM64) workers for the services, with chatHost pointed at a commodity GPU box (2× RTX 2080 + 1× RTX 3090 running Ollama) serving the open-weight chat models to the cluster. Three gaming GPUs host the whole platform; you don’t need a datacenter. See Built on a homelab, not a datacenter.

A bare install seeds a single local Ollama provider (ollama-local) on first boot, so the stack chats with zero API keys. Providers are pluggable: bootstrap seeds one, and you add others at runtime. To make AWS Bedrock the default chat and flows provider instead, set bootstrapProvider.enabled: true and supply AWS credentials:

bootstrapProvider:
  enabled: true
  type: aws-bedrock
  chatModel: anthropic.claude-sonnet-4-6

secrets:
  awsAccessKeyId: "AKIA..."
  awsSecretAccessKey: "..."
  awsRegion: us-east-1

Embeddings stay on the in-cluster Ollama (nomic-embed-text, 768 dimensions) regardless of the chat provider. Every provider beyond the bootstrap one is added at runtime in the admin console under LLM provider management and persisted in the database. See Configuration for the full provider surface.

Enable MCP servers

The chart enables a default set of MCP servers for the operations use case: web, admin, kubernetes, and prometheus. The Kubernetes and Prometheus MCPs are controlled by structured toggles under mcps:

mcps:
  enabled: "web,knowledge,admin,kubernetes,prometheus"
  kubernetes:
    enabled: true       # uses the mcp-proxy pod ServiceAccount + read-only RBAC
  prometheus:
    enabled: true
    url: "http://prometheus:9090"

The Kubernetes MCP authenticates with the mcp-proxy pod’s ServiceAccount token and a read-only ClusterRole. Setting mcps.kubernetes.enabled: false ships no RBAC. The Prometheus MCP queries the in-cluster prometheus service and needs no credentials. The chart disables the cloud servers (aws, azure, gcp), GitHub, and Loki by default — a barebones cluster has no credentials or Loki endpoint for them.

Under the hood, each MCP is gated by an OpenAgentic_<NAME>_MCP_DISABLED environment flag, templated from the structured toggles above. The mcps.enabled comma-separated string is kept for back-compatibility and UI display; the per-MCP environment flags are the authoritative switches. (The mcps.enabled default still lists a legacy knowledge token, but there is no knowledge server — it was removed upstream and replaced by the per-tool meta cascade, so the token is inert.)

The cloud MCPs (AWS, Azure, GCP) are disabled by default because a barebones install has no credentials for them. Enable them in your values file and supply credentials. In the self-hosted build, cloud MCPs authenticate with static service-account or static credentials only — for example, GCP_CREDENTIALS_JSON (or a mounted service-account key) for GCP, and AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY for AWS.

Note: IdP-based on-behalf-of (OBO) delegation for cloud MCPs is an Enterprise feature. The self-hosted chart does not perform per-user OBO; cloud MCP calls run with the static service-account credentials you provide.

Expose the UI with an Ingress

Set ingress.enabled: true with a host to publish the UI. The chart’s Ingress routes / to the ui service on port 80 using the nginx ingress class, and adds SSE-friendly annotations (long read and send timeouts, buffering off) for streaming chat and flow runs. For HTTPS, set ingress.tlsSecret to the name of an existing kubernetes.io/tls secret in the release namespace:

ingress:
  enabled: true
  className: nginx
  host: openagentic.example.com
  tlsSecret: openagentic-tls

The chart consumes a pre-existing TLS secret; it does not integrate cert-manager directly. To issue and renew the certificate automatically, install cert-manager separately, create an issuer, and create a Certificate whose secretName matches the value you set in ingress.tlsSecret. cert-manager then populates that secret, and the Ingress serves HTTPS once the certificate is Ready. Verify the certificate and the Ingress:

kubectl get certificate -n openagentic
kubectl get ingress -n openagentic

Uninstall

Because the datastores are in-chart, uninstalling the release removes them too. PersistentVolumeClaims are retained by default — delete them explicitly to remove the data.

helm uninstall openagentic -n openagentic
kubectl delete pvc -l app.kubernetes.io/instance=openagentic -n openagentic
kubectl delete namespace openagentic

What’s next

• After the pods are Running, tune providers, MCP servers, and governance at runtime in the admin console. See Configuration.
• For multi-tenant managed hosting with enterprise controls, including IdP-based OBO for cloud MCPs, see AgenticWork.