Helm chart for deploying OpenKB (Open LLM Knowledge Base by VectifyAI) on Kubernetes. It runs the OpenKB REST API and the bundled Knowledge Workbench web UI, stores knowledge bases on a PersistentVolumeClaim, keeps LLM API keys in a Kubernetes Secret, and turns on bearer-token authentication by default. A Dockerfile for an OpenKB container image is included, because upstream does not publish one.
helm repo add openkb https://fireweave-hq.github.io/openkb-helm
helm repo update
helm install openkb openkb/openkb --namespace openkb --create-namespace \
--set image.repository=<your-registry>/openkb --set image.tag=0.5.0rc1There is no public OpenKB image yet, so build docker/Dockerfile and push it first (docs/image.md). The full walkthrough, including the credentials Secret, is under Install.
This is a community chart. It is maintained separately from Vectify AI, it is not an official OpenKB project, and Vectify AI has not endorsed it. The chart installs the upstream Python package and does not fork the application.
Looking for a different OpenKB? This chart is for VectifyAI/OpenKB, the LLM knowledge base built on PageIndex. It is unrelated to mrvautin/openKB, the Node.js FAQ app.
Contents: What you get · Prerequisites · Install · Configuration · Upgrade · Backup · Security · Image · FAQ
One Deployment runs openkb-web, which is the openkb.api:main console script. That process serves:
- the REST API under
/api/v1 - the OpenAPI document at
/openapi.jsonand the Swagger UI at/docs - the Knowledge Workbench static bundle at
/, when the wheel includesopenkb/web(the published0.5.0rc1wheel does)
Knowledge bases are directories on a PersistentVolumeClaim. LLM credentials stay in a Kubernetes Secret.
| Chart | 0.1.0 |
| Upstream package | 0.5.0rc1 (git tag v0.5.0-rc1) |
| License of this repo | Apache-2.0. Upstream OpenKB is also Apache-2.0. See NOTICE. |
v0.4.5 is the newest stable OpenKB tag and does not contain the web server. This chart tracks 0.5.0rc1 because that is the first PyPI release that does. main has moved past that tag; this chart does not follow unreleased commits.
Ingress or Service :7566
|
v
Pod openkb-web --host 0.0.0.0 --port 7566
|
+-- PVC /var/lib/openkb/kbs OPENKB_KB_ROOT
+-- PVC /var/lib/openkb/home HOME (~/.config/openkb)
+-- emptyDir /tmp working directory and temp files
+-- Secret OPENKB_API_TOKEN, LLM_API_KEY, ...
The process default bind address is 127.0.0.1. The chart passes --host 0.0.0.0 so the Service can reach it. The port 7566 is the upstream default.
There is no /health or /ready route. Probes use GET /openapi.json, which FastAPI serves as soon as the process is up. That route is not protected by the bearer token. The API routes are.
Details and file references: docs/architecture.md.
- Kubernetes 1.28 or newer. As of November 2026 the Kubernetes project supports 1.35, 1.36, and 1.37. This chart only uses stable APIs.
- Helm 3 or 4 (
helm4.0.4 was used to render and test it). - A StorageClass that can provision a PersistentVolume, unless you set
persistence.existingClaimorpersistence.enabled=false. - A container image. Upstream does not publish one. Build docker/Dockerfile or use an image you have pushed. See docs/image.md.
- An LLM API key if you want query, chat, or compile to call a model. The server starts without one.
The chart repository is served from GitHub Pages at https://fireweave-hq.github.io/openkb-helm. Each vX.Y.Z tag publishes a chart package to GitHub Releases and updates index.yaml there.
helm repo add openkb https://fireweave-hq.github.io/openkb-helm
helm repo update
helm search repo openkb --versions
helm install openkb openkb/openkb \
--namespace openkb \
--create-namespace \
-f values.yamlPrint the default values to start your own values.yaml:
helm show values openkb/openkb > values.yamlThe Pod still needs an image your cluster can pull. See Prerequisites.
Create the credentials Secret first. The chart will not store these values in a ConfigMap.
kubectl create namespace openkb
kubectl -n openkb create secret generic openkb-credentials \
--from-literal=OPENKB_API_TOKEN="$(openssl rand -hex 32)" \
--from-literal=LLM_API_KEY="paste-your-llm-key"PAGEINDEX_API_KEY is optional and only needed for PageIndex Cloud. OPENAI_API_BASE is optional and is the OpenAI-compatible base URL.
helm upgrade --install openkb ./charts/openkb \
--namespace openkb \
--create-namespace \
-f examples/minimal-values.yamlBuild and load the image before the Pod can start. With the default values the image reference is openkb:0.5.0rc1:
docker build -f docker/Dockerfile -t openkb:0.5.0rc1 .
# kind: kind load docker-image openkb:0.5.0rc1Point image.repository and image.tag at your registry if the cluster cannot see a local image.
auth.token, llm.apiKey, and llm.pageindexApiKey work and are written to a chart-managed Secret. Helm also stores those values in the release Secret. Prefer auth.existingSecret.
If you set neither auth.existingSecret nor auth.token, Helm generates OPENKB_API_TOKEN and reuses it on later upgrades only when the upgrade can read the existing Secret (lookup). helm template and helm upgrade --dry-run=client cannot see the cluster, so they print a new token every time. Do not apply that output over a release you care about.
| Topic | Example |
|---|---|
| Token in an existing Secret | examples/minimal-values.yaml |
| Ingress and TLS | examples/ingress-tls-values.yaml |
| Existing PVC | examples/existing-pvc-values.yaml |
| LLM provider, base URL, PageIndex, model | examples/llm-providers-values.yaml |
| NetworkPolicy | examples/networkpolicy-values.yaml |
The chart README lists the values: charts/openkb/README.md.
| Key | Required | Where it is read |
|---|---|---|
OPENKB_API_TOKEN |
Yes, unless auth.allowUnauthenticated |
Bearer token for /api/v1/* |
LLM_API_KEY |
For model calls | LiteLLM credential bundle |
PAGEINDEX_API_KEY |
No | PageIndex Cloud. Local indexing is the default |
OPENAI_API_BASE |
No | OpenAI-compatible gateway URL |
auth.allowUnauthenticated: true omits OPENKB_API_TOKEN. Upstream then serves the API with no authentication. Leave it false.
Retrieve the token without printing it into a chart note:
kubectl get secret -n openkb openkb-credentials \
-o jsonpath='{.data.OPENKB_API_TOKEN}' | base64 -d && echoThe Workbench asks for the token once and keeps it in the browser. API clients send Authorization: Bearer <token>.
persistence.enabled defaults to true. The claim is named <release>-data (openkb-data when the release is openkb) and is annotated helm.sh/resource-policy: keep.
OPENKB_KB_ROOT is /var/lib/openkb/kbs. HOME is /var/lib/openkb/home, because OpenKB stores global config at Path.home() / ".config" / "openkb" and does not read XDG_CONFIG_HOME.
Replicas default to 1. The default access mode is ReadWriteOnce, and the Deployment strategy is Recreate, so an upgrade does not start a second Pod before the volume is free. More than one replica needs ReadWriteMany and is still a poor fit: the file watcher is in-process.
helm uninstall does not delete the PVC. To delete the knowledge base:
kubectl delete pvc -n openkb openkb-dataservice.type defaults to ClusterIP. Set ingress.enabled to expose the Workbench. Use a long proxy read timeout. Query, chat, and document upload streams are Server-Sent Events and can run for minutes. The nginx annotations in examples/ingress-tls-values.yaml are examples, not a requirement.
OpenKB talks to models through LiteLLM. The REST server passes LLM_API_KEY (and OPENAI_API_BASE when set) on each request. One key covers OpenAI, Anthropic, Gemini, DeepSeek, and any other LiteLLM provider. The chart does not invent per-provider variables.
The model is not an environment variable. Upstream default is gpt-5.4, language en, pageindex_threshold 20. Set kbDefaults.model to a LiteLLM id (gpt-5.4, or anthropic/claude-sonnet-4-6) and the chart writes config.yaml into the working directory. REST /init copies that file into a new knowledge base when the request does not include a model. You can also change the model later in the Workbench.
OAuth providers (chatgpt, github_copilot) expect an interactive device login. This chart does not set that up.
networkPolicy.enabled is false. Turning it on allows ingress to port 7566 and egress to DNS (UDP/TCP 53) and TCP 443. Anything else, including an LLM on another port, needs networkPolicy.extraEgress. The policy is off by default so the first install can reach an LLM API.
helm upgrade openkb openkb/openkb \
--namespace openkb \
-f values.yamlThe PVC name does not change across upgrades. Keep using the same auth.existingSecret so the bearer token stays put.
0.5.0rc1 is a release candidate. Moving appVersion to a later upstream release is a chart change; read that release's notes before you roll it out. Knowledge-base files are plain Markdown and YAML on the volume.
See docs/backup.md. Short version: snapshot the PVC, or copy /var/lib/openkb. Restoring that tree and mounting it with persistence.existingClaim brings the knowledge bases back. A KB-local .env on that volume may contain an LLM key if someone passed api_key to /init. The chart itself does not write API keys onto the volume.
helm uninstall openkb --namespace openkb
kubectl delete pvc -n openkb openkb-data # only when you want the data gone
kubectl delete secret -n openkb openkb-credentialsThe second command is required because of helm.sh/resource-policy: keep.
- Authentication is on unless you set
auth.allowUnauthenticated. - The container runs as UID 1000, non-root, read-only root filesystem, all capabilities dropped,
RuntimeDefaultseccomp, not privileged. - The ServiceAccount token is not mounted. OpenKB does not call the Kubernetes API.
/openapi.jsonand/docsare unauthenticated even when the token is set. That is upstream behavior. Do not treat the OpenAPI document as a secret. Do not put the token in a probe header; it would show up in the Pod spec.- Report vulnerabilities in this chart with GitHub private vulnerability reporting. There is no bounty.
Build and publishing steps: docs/image.md.
docker build -f docker/Dockerfile -t openkb:0.5.0rc1 .The Dockerfile installs openkb[web]==0.5.0rc1 from PyPI, plus the FastAPI, uvicorn, and python-multipart versions pinned in the upstream lock file at v0.5.0-rc1. It does not clone OpenKB or rebuild the frontend. The wheel already contains openkb/web/index.html.
./scripts/test.shThat lints the chart, renders the install scenarios, runs helm unittest, runs kubeconform when the binary is available, and packages the chart. It does not install into a cluster.
make docker-buildNo. As of OpenKB v0.5.0-rc1, Vectify AI publishes the Python package on PyPI and the source on GitHub, but no Helm chart and no container image. This repository is a community chart that installs that PyPI release.
Not from upstream. docker/Dockerfile builds one from openkb[web]==0.5.0rc1 and runs openkb-web. CI scans it with Trivy. You push it to your own registry.
0.5.0rc1, the first release that ships the REST API and Knowledge Workbench. The stable v0.4.5 is CLI-only. See Version.
Any provider LiteLLM supports, including OpenAI, Anthropic, Gemini, DeepSeek, and OpenAI-compatible gateways through llm.openaiApiBase. See LLM providers.
Yes. Run the same image with docker run, as shown in docs/image.md, or install openkb[web] from PyPI.
Chart and image bugs go to this repository's issues. Bugs in the OpenKB application go to VectifyAI/OpenKB.
See CONTRIBUTING.md. Maintainers are the owners of this repository. This file does not name a person.
Apache-2.0 for this chart, the Dockerfile, and these docs. Upstream OpenKB remains under its own Apache-2.0 copyright. See LICENSE and NOTICE.