Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
OpenViking Helm Chart
Deploy OpenViking on Kubernetes using Helm.
Prerequisites
- Kubernetes 1.24+
- Helm 3.x
- A storage class that supports
ReadWriteOncepersistent volumes (for RocksDB data)
Installation
Quick Start
helm install openviking ./deploy/helm/openviking \
--set-string config.server.root_api_key="YOUR_ROOT_API_KEY" \
--set-string config.embedding.dense.api_key="YOUR_VOLCENGINE_API_KEY" \
--set-string config.vlm.api_key="YOUR_VOLCENGINE_API_KEY"
The chart deploys ghcr.io/volcengine/openviking:latest by default. To choose
a different image tag:
# newest image from the main branch
helm upgrade --install openviking ./deploy/helm/openviking --set image.tag=main
# pinned release image
helm upgrade --install openviking ./deploy/helm/openviking --set image.tag=v0.3.17
# use the default latest image
helm upgrade --install openviking ./deploy/helm/openviking --set image.tag=
We recommend the ghcr.io image. If ghcr.io is hard to reach, add
--set image.repository=openviking-cn-beijing.cr.volces.com/volcengine/openviking.
Install with Custom Values
Create a my-values.yaml file:
replicaCount: 1
resources:
limits:
cpu: "4"
memory: 8Gi
requests:
cpu: "1"
memory: 2Gi
persistence:
size: 50Gi
storageClass: "gp3"
config:
storage:
workspace: /app/.openviking/openviking_workspace
log:
level: INFO
output: stdout
server:
host: "0.0.0.0"
port: 1933
workers: 1
root_api_key: "your-secret-key"
embedding:
dense:
api_base: "https://ark.cn-beijing.volces.com/api/v3"
api_key: "your-volcengine-api-key"
provider: "volcengine"
dimension: 1024
model: "doubao-embedding-vision-251215"
input: "multimodal"
max_concurrent: 10
vlm:
api_base: "https://ark.cn-beijing.volces.com/api/v3"
api_key: "your-volcengine-api-key"
provider: "volcengine"
model: "doubao-seed-2-0-lite-260428"
temperature: 0.0
max_retries: 2
thinking: false
max_concurrent: 100
Then install:
helm install openviking ./deploy/helm/openviking -f my-values.yaml
Using Secrets for API Keys
For production, avoid putting API keys directly in values. Use extraEnv with
Kubernetes secrets instead:
# Create a secret
kubectl create secret generic openviking-api-keys \
--from-literal=root-api-key="YOUR_ROOT_API_KEY" \
--from-literal=embedding-api-key="YOUR_KEY" \
--from-literal=vlm-api-key="YOUR_KEY"
Then reference it in your values:
config:
server:
root_api_key: "${OPENVIKING_ROOT_API_KEY}"
embedding:
dense:
api_key: "${OPENVIKING_EMBEDDING_API_KEY}"
vlm:
api_key: "${OPENVIKING_VLM_API_KEY}"
extraEnv:
- name: OPENVIKING_ROOT_API_KEY
valueFrom:
secretKeyRef:
name: openviking-api-keys
key: root-api-key
- name: OPENVIKING_EMBEDDING_API_KEY
valueFrom:
secretKeyRef:
name: openviking-api-keys
key: embedding-api-key
- name: OPENVIKING_VLM_API_KEY
valueFrom:
secretKeyRef:
name: openviking-api-keys
key: vlm-api-key
OpenViking expands environment variables inside ov.conf at startup, so the
ConfigMap can contain placeholders while the actual secrets stay in Kubernetes
Secrets.
OpenViking Gateway
Set gateway.enabled: true to run OpenViking Gateway
inside the server container. The chart adds gateway.enabled to ov.conf and stores
gateway data in <persistence.mountPath>/gateway on the persistent volume. There is no
sidecar and no extra Service port: clients use /gateway on the server port, and the existing Ingress
forwards every path to OpenViking.
Model requests stream, so the Ingress must turn off response buffering and allow request bodies of at least 32 MiB and timeouts of 600 seconds. The chart does not set these annotations for you. With NGINX:
gateway:
enabled: true
existingSecret: "" # optional: Secret with a management-key entry
config:
server:
auth_mode: api_key
gateway:
public_url: https://ov.example.com
ingress:
enabled: true
className: nginx
annotations:
nginx.ingress.kubernetes.io/proxy-buffering: "off"
nginx.ingress.kubernetes.io/proxy-request-buffering: "off"
nginx.ingress.kubernetes.io/proxy-body-size: 32m
nginx.ingress.kubernetes.io/proxy-read-timeout: "600"
nginx.ingress.kubernetes.io/proxy-send-timeout: "600"
hosts:
- host: ov.example.com
paths:
- path: /
pathType: Prefix
Set config.gateway.public_url to the address clients use, without /gateway; Studio's
setup guides and file upload links are built from it, with /gateway appended. Clients use
https://ov.example.com/gateway/v1 (OpenAI-compatible) or https://ov.example.com/gateway
(Anthropic).
Secrets
The gateway encrypts its stored data with the server's config.encryption settings; with
server encryption off, it stores them unencrypted.
gateway.existingSecret optionally names a Secret. Both entries are optional:
management-key(at least 32 characters) is passed asOPENVIKING_GATEWAY_MANAGEMENT_KEY. With it, only requests that carry this key can change upstreams and context profiles; see Gateway management key.encryption-keyis the v0.5.0 gateway key, passed asOPENVIKING_GATEWAY_ENCRYPTION_KEY. It is only read once, to migrate data stored by the v0.5.0 gateway.
kubectl create secret generic openviking-gateway \
--from-literal=management-key="$(openssl rand -base64 32)"
Keep replicaCount: 1: the gateway's SQLite databases serve one pod only. The default
local vectordb also locks the workspace to a single worker, so raise the server's workers
setting only after switching to a remote vectordb backend such as VikingDB.
Upgrading from the sidecar chart
- Keep the persistent volume. On first start the server re-encrypts the gateway's stored
data with its own encryption settings, reading the old key from the
encryption-keyentry ofgateway.existingSecretor fromencryption.keyin the gateway storage directory. If old encrypted data exists and neither is present, the server refuses to start. Keep theencryption-keyentry for the upgrade release only; after the server has started once, the key is no longer read and you can remove the entry. - Remove
gateway.port,gateway.workersandgateway.resources. - Remove
host,port,workers,url,openviking_urlandadmin_token_envfromconfig.gateway. The server ignores them with a startup warning. - Point
config.gateway.public_urlat the server's public address, not port 1935, and move clients to the server port and the/gatewayprefix:http://host:1935/v1becomeshttps://ov.example.com/gateway/v1. The management API moved from/api/v1/admin/gateway/...to/gateway/admin/.... - The shared admin token is gone and does not act as a management key. To restrict
changes to upstreams and context profiles, add a
management-keyentry togateway.existingSecret.
For deployment, Studio management, backups and troubleshooting, see OpenViking Gateway deployment and operations.
Standalone OpenViking Gateway
Use deploy/helm/openviking-gateway when the gateway needs independent replicas,
rollouts and a Service. The openviking chart's gateway.enabled runs inside the
OpenViking Server and follows its single-replica lifecycle; it is still the
simplest choice when you operate both together.
The standalone chart targets unreleased gateway features: until appVersion
names a published release, image.tag is required and must name a compatible build.
To release the chart, set appVersion to the release without the v and bump version,
then run PYTHONPATH=. python scripts/gateway_chart_check.py and the gateway kind suite
(tests/gateway/e2e) against that release image.
helm upgrade --install gateway ./deploy/helm/openviking-gateway \
--set-string image.tag='<gateway-image-tag>' \
--set-string config.openviking_url=https://ov.example.com
By default this creates a single SQLite replica, PVC, and ClusterIP Service on
port 80, forwarding to 1935. config renders a JSON gateway.conf; host, port
and storage_path are fixed by the chart. The OpenViking endpoint must use API-key
authentication. A default StorageClass is sufficient, or select one with
persistence.storageClass or use persistence.existingClaim.
Set both config.storage.kernel and config.storage.management to redis, and
set config.storage.redis (endpoints, password_env: OPENVIKING_GATEWAY_REDIS_PASSWORD),
before increasing replicaCount. Redis deployments use RollingUpdate and do
not create a PVC; multiple replicas get a PDB. SQLite uses Recreate and rejects
multiple replicas. Disabling persistence uses emptyDir and loses SQLite state
when the Pod is replaced. PVCs are retained after uninstall.
Use existingSecret entries management-key, redis-password and root-key
for the management credential, Redis password and encryption root key. Local
and KMS encryption require a pre-generated root key, shared read-only by all
replicas. Other credentials use $VAR references in config and extraEnv
with secretKeyRef. External Secret changes require a Deployment restart.
The chart provides no Ingress. Its Service and Deployment share a name; use
fullnameOverride to pin it. The stable selectors are app.kubernetes.io/name
and app.kubernetes.io/instance. service.type, service.loadBalancerSourceRanges,
and optional networkPolicy.ingressFrom support external routing. All probes
use /health; startup allows 300 seconds, preStop sleeps 15 seconds, and the
default termination grace is 660 seconds.
For Redis settings, encryption key creation, a complete multi-replica values example, shutdown timing and operations, see the gateway operations guide.
Configuration
| Parameter | Description | Default |
|---|---|---|
replicaCount |
Number of replicas | 1 |
image.repository |
Container image repository | ghcr.io/volcengine/openviking |
image.tag |
Container image tag (latest, main, pinned release, or empty for latest) |
latest |
image.pullPolicy |
Image pull policy | Always |
service.type |
Kubernetes service type | ClusterIP |
service.port |
Service port | 1933 |
persistence.enabled |
Enable persistent storage | true |
persistence.size |
PVC size | 20Gi |
persistence.storageClass |
Storage class name | "" (default) |
persistence.mountPath |
Container path for OpenViking persistent state | /app/.openviking |
bot.enabled |
Start vikingbot alongside the API server | false |
persistence.existingClaim |
Use an existing PVC | "" |
resources.limits.cpu |
CPU limit | 2 |
resources.limits.memory |
Memory limit | 4Gi |
resources.requests.cpu |
CPU request | 500m |
resources.requests.memory |
Memory request | 1Gi |
ingress.enabled |
Enable ingress | false |
config.server.root_api_key |
API key required when server binds to 0.0.0.0 | "" |
config |
Full ov.conf configuration object | See values.yaml |
extraEnv |
Additional environment variables | [] |
gateway.enabled |
Run OpenViking Gateway inside the server container, under /gateway on the server port |
false |
gateway.existingSecret |
Optional Secret with optional entries management-key (required to change upstreams and context profiles) and encryption-key (v0.5.0 key, read once for migration) |
"" |
Upgrading
helm upgrade openviking ./deploy/helm/openviking -f my-values.yaml
The deployment uses a Recreate strategy to avoid data corruption from
multiple pods accessing the same RocksDB volume simultaneously.
Uninstalling
helm uninstall openviking
Note: The PersistentVolumeClaim is retained by Helm and becomes orphaned after uninstall. Delete it explicitly to remove the stored data:
kubectl delete pvc openviking-data