Skip to content
EYAS Docs

Kubernetes

What this is for. Kubernetes is the third install path: a Helm chart for a real cluster. Use it when you need PVC-backed data/, an Ingress, probes, and secrets as Kubernetes objects. The raw YAML files at the top of deploy/k8s/ are legacy starters — for any real deployment use Helm deploy/k8s/helm/eyas/.

See repo deploy/k8s/README.md and the chart deploy/k8s/helm/eyas/.

When to use it

Section titled “When to use it”
  • More than one replica or a shared cluster (still never two writers on one SQLite file — see multi-instance).
  • You already run Ingress + a StorageClass.
  • Secrets should come from a Kubernetes Secret or External Secrets Operator, not a file on disk.

Typical workflow

Section titled “Typical workflow”
  1. Kubernetes 1.28+, Helm 3.12+, a reachable image, an Ingress controller, a StorageClass.
  2. kubectl create namespace eyas. Create the master key Secret (eyas-master-key / master-key) before helm install.
  3. Pull-secret if the registry is private. Set image.pullSecrets in values.
  4. helm install the chart under deploy/k8s/helm/eyas/ with your values (image, EYAS_PORT, PVC, Ingress).
  5. Probes hit /api/v1/health (or /web/health as configured). Open the Ingress host.

Features

Section titled “Features”

Typical values: image, EYAS_PORT, PVC for data, secrets for keys, Ingress, probes on /api/v1/health or /web/health as configured.

Cloud-provider StorageClass names and load-balancer annotations go in your values file. Keep the master key in a password manager — losing it loses the secrets vault.

Data directory on the volume. With the chart’s default mount (/app/data) nothing needs setting: the database and the memory vault are on the persistent volume. If you point EYAS_DATA_DIR at a different mount, the vault moves there too — it is always <data dir>/vault — together with the database. See Configuration — Data directory and vault.

Kernel file sandbox. The EYAS image does not include bubblewrap (it is LGPL; installing it is the operator’s choice). For the CLI providers’ kernel file sandbox, the container needs bubblewrap (bwrap), socat for Claude Code, and unprivileged user namespaces — which many clusters and container runtimes switch off. Without them EYAS still refuses every request it sees and shows the sandbox as Unavailable; with security.cliSandbox: required, CLI turns with tools are refused. eyas doctor reports it on its CLI sandbox line. See Providers — Kernel file sandbox.

Memory headroom for a large import. The chart’s default limit is 1Gi, which leaves room for a data-port import: one container file is held in memory while every unit inside it is rendered, and how much that costs depends on the file — about three times its size for a line-per-turn transcript, seven or more for a chat export parsed whole. A 90 MB chat export peaks near 900 MiB resident, inside 1Gi but not by much; the legacy starter YAML at the top of deploy/k8s/ sets 512Mi and cannot hold it. The peak follows your largest single file, not the size of the scan, so raise the limit before importing anything bigger. See Data import & export.

Section titled “Related”