Getting started with Kubernetes
Install Akmatori in your Kubernetes cluster with the official Helm chart. The chart runs the same services and images as the Docker Compose install, with the same isolation: the agent worker cannot reach the database, and only one proxy Service accepts outside traffic.
What the chart installs
| Component | Kind | Notes |
|---|---|---|
akmatori-api | Deployment | REST API, webhooks, crons, agent WebSocket. One replica. |
akmatori-agent | Deployment | The agent worker. UID 1001, no database access. |
akmatori-mcp-gateway | Deployment | Runs tool calls with credentials from the database. |
akmatori-frontend | Deployment | The web UI. |
akmatori | Deployment + Service | nginx proxy, the only entry point. |
akmatori-postgres | StatefulSet | PostgreSQL 16. Optional: you can use an external database. |
You need:
- Kubernetes 1.27 or later,
kubectl, and Helm 3.14 or later (Helm 4 works too). - A default StorageClass, or set
persistence.storageClassandpostgresql.persistence.storageClass. - About 0.5 vCPU and 1.5 GiB of memory for requests. The agent uses more while it investigates.
- Outbound HTTPS from the cluster to your LLM provider and to
ghcr.io. - For the network isolation: a CNI that enforces NetworkPolicy (Calico, Cilium and others). On other CNIs the install still works, but the policies have no effect.
Install
Each release publishes the chart to GHCR with the same version as the release. The chart version also sets the image tag.
helm upgrade --install akmatori oci://ghcr.io/akmatori/charts/akmatori \
--version 0.5.0 --namespace akmatori --create-namespace --wait
kubectl -n akmatori get pods All six pods must show Running and 1/1. The first start takes 1 to 3 minutes: the API waits for PostgreSQL and runs the database migrations.
Open the UI and set the admin password
The proxy Service is internal by default. Use a port-forward for the first login:
kubectl -n akmatori port-forward svc/akmatori 8080:80 Open http://localhost:8080. The setup wizard asks for the admin password (user admin). Until you set it, the agent worker log shows Unexpected server response: 503. This is normal. After the setup, the worker connects. Then add your LLM in Settings → AI models, as in the Docker Compose guide.
adminPassword or existingAuthSecret in your values. Expose Akmatori
Send all traffic to the akmatori Service. The proxy keeps the MCP tool endpoints and the agent WebSocket internal, so do not route paths to the other Services. Example with Traefik and cert-manager (tested with Traefik 3.7):
baseUrl: https://akmatori.example.com
ingress:
enabled: true
className: traefik
annotations:
cert-manager.io/cluster-issuer: letsencrypt
hosts:
- host: akmatori.example.com
tls:
- secretName: akmatori-tls
hosts: [akmatori.example.com]helm upgrade akmatori oci://ghcr.io/akmatori/charts/akmatori --version 0.5.0 \
-n akmatori --reset-then-reuse-values -f values-prod.yaml The chart creates a standard Ingress, so other controllers work too. Context file uploads can be up to 10 MB: if your controller has a lower body limit, raise it. ingress-nginx is retired (no releases or security fixes after March 2026) and has a 1 MB default; if you still run it, add nginx.ingress.kubernetes.io/proxy-body-size: 11m to ingress.annotations.
Without an Ingress controller, set proxyServer.service.type=LoadBalancer and limit the sources with proxyServer.service.loadBalancerSourceRanges. Put TLS in front of it. Alert webhooks use the same address: https://<host>/webhook/alert/<instance-uuid>.
Main values
| Value | Default | Description |
|---|---|---|
image.tag | chart version | Image tag for the four Akmatori images. main tracks the main branch. |
baseUrl | empty | Public URL for links in Slack and other channels. |
adminPassword | empty | Skip the setup wizard. |
persistence.size | 10Gi | Shared data volume for skills, context files and incident work directories. |
postgresql.enabled | true | false uses externalDatabase.url or externalDatabase.existingSecret. |
proxy.httpsProxy | empty | Outbound HTTP proxy for the API, gateway and agent. |
networkPolicy.agentEgressDenyCIDRs | [] | Addresses the agent must not reach. Set it for an external database. |
The full list, with external PostgreSQL, proxies, the security model and troubleshooting, is in the Kubernetes guide on GitHub.
Upgrade
Read the release notes first: some releases change or delete data on the first start. Back up the database, then upgrade:
kubectl -n akmatori exec akmatori-postgres-0 -- pg_dump -U akmatori akmatori | gzip > akmatori-$(date +%F).sql.gz
helm upgrade akmatori oci://ghcr.io/akmatori/charts/akmatori --version <new-version> \
-n akmatori --reset-then-reuse-values --wait Use --reset-then-reuse-values, not --reuse-values: the second one keeps your values but skips the new defaults of a newer chart. The chart keeps the database password, and the admin password if you set it, in the Secret akmatori-secrets across upgrades. The API and the agent stop before their new pods start, so there is a short downtime.
Uninstall
helm uninstall akmatori -n akmatori
# Removes all data, including the database:
kubectl delete namespace akmatoriHelm keeps the data volume, the PostgreSQL volume and the Secret, so a new install finds the old data. Delete the namespace to remove all data.