Skip to main content

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

ComponentKindNotes
akmatori-apiDeploymentREST API, webhooks, crons, agent WebSocket. One replica.
akmatori-agentDeploymentThe agent worker. UID 1001, no database access.
akmatori-mcp-gatewayDeploymentRuns tool calls with credentials from the database.
akmatori-frontendDeploymentThe web UI.
akmatoriDeployment + Servicenginx proxy, the only entry point.
akmatori-postgresStatefulSetPostgreSQL 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.storageClass and postgresql.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.

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

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

Set the admin password before you expose the UI. In setup mode, the first visitor sets the password. To skip the wizard, set 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):

values-prod.yaml
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]
bash
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

ValueDefaultDescription
image.tagchart versionImage tag for the four Akmatori images. main tracks the main branch.
baseUrlemptyPublic URL for links in Slack and other channels.
adminPasswordemptySkip the setup wizard.
persistence.size10GiShared data volume for skills, context files and incident work directories.
postgresql.enabledtruefalse uses externalDatabase.url or externalDatabase.existingSecret.
proxy.httpsProxyemptyOutbound 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:

bash
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

bash
helm uninstall akmatori -n akmatori
# Removes all data, including the database:
kubectl delete namespace akmatori

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