Skip to content

Kubernetes Helm

Jump to bottom
Sia edited this page May 31, 2026 · 3 revisions

Kubernetes (Helm chart)

Lives at helm/vibe-coder-server/ inside the source repository.

Single-tenant by design. vibe-coder-server is a single-user dev machine (see CLAUDE.md §1). The chart is a convenience for operators who run k8s anyway — not a step toward multi-tenant SaaS. replicas is locked at 1 and workspace data lives on a ReadWriteOnce PVC.

When to use it

Pick docker compose if:

  • You're running on a single host
  • You just want the Quick Start experience

Pick Helm if:

  • You already run k8s and want vibe-coder colocated with the rest of your workload
  • You want managed PostgreSQL (postgres.enabled=false + external host)
  • You want TLS via cert-manager + ingress-nginx

Quick install (in-cluster PostgreSQL)

helm install vibe ./helm/vibe-coder-server \
  --set postgres.password=$(openssl rand -hex 24)

kubectl get pods -l app.kubernetes.io/instance=vibe
# vibe-…              1/1 Running
# vibe-postgres-0     1/1 Running

kubectl port-forward svc/vibe 17880:17880
# open http://localhost:17880/setup

External ingress + TLS

helm install vibe ./helm/vibe-coder-server \
  --set postgres.password=$(openssl rand -hex 24) \
  --set ingress.enabled=true \
  --set ingress.host=vibe.example.com \
  --set ingress.tls.enabled=true \
  --set ingress.tls.secretName=vibe-tls \
  --set env.VIBECODER_CORS_ALLOWED_HOSTS=https://vibe.example.com

The chart pre-sets the nginx-friendly proxy timeouts (proxy-read-timeout, proxy-send-timeout = 3600) so WebSocket connections survive long Claude turns.

External managed PostgreSQL

Disable the in-cluster sidecar and point at any reachable PG instance — RDS, Cloud SQL, on-prem, anything that supports PG 14+:

helm install vibe ./helm/vibe-coder-server \
  --set postgres.enabled=false \
  --set env.VIBECODER_DB_HOST=my-pg.svc.cluster.local \
  --set env.VIBECODER_DB_PORT=5432 \
  --set env.VIBECODER_DB_NAME=vibecoder \
  --set env.VIBECODER_DB_USER=vibecoder \
  --set-string secretEnv.VIBECODER_DB_PASSWORD=$DB_PASSWORD

secretEnv keys become a Secret mounted as envFrom, so the value never appears in pod env-vars output.

What's in the chart

helm/vibe-coder-server/
├── Chart.yaml             # appVersion mirrors siamakerlab/vibe-coder-server:<tag>
├── values.yaml            # every key documented inline
├── README.md              # operator-facing quick install
└── templates/
    ├── _helpers.tpl       # fullname / labels / serviceAccountName
    ├── deployment.yaml    # replicas=1, strategy=Recreate, RWO workspace mount
    ├── service.yaml       # ClusterIP, port 17880
    ├── ingress.yaml       # optional (HTTP + WS); cert-manager friendly
    ├── postgres.yaml      # optional StatefulSet sidecar
    ├── pvc.yaml           # workspace + (optional) postgres RWO PVCs
    ├── secret.yaml        # PG password + arbitrary env Secret
    └── serviceaccount.yaml

Values reference (highlights)

Key Default Purpose
image.repository siamakerlab/vibe-coder-server Image registry/repo
image.tag 0.47.0 Pin the version — bump per release
postgres.enabled true Spin a sidecar StatefulSet. Disable for external PG.
postgres.password "" Required when sidecar enabled. Pass via --set.
postgres.storage 5Gi Sidecar PVC size
workspace.storage 50Gi Workspace PVC size (sources + builds + caches)
resources 500m / 2Gi req — 4 cpu / 8Gi limit Generous JVM headroom for Gradle daemons
ingress.enabled false Set true + provide host to expose externally
ingress.tls.enabled / secretName false / "" TLS termination
env {} Pass-through container env (same keys as docker .env)
secretEnv {} Secret-backed env (e.g. ANTHROPIC_API_KEY)
serviceAccount.create / name true / "" SA management

Full reference: values.yaml.

Limitations

  • Single replica only. Workspace + agent-session state live on the RWO PVC. Multiple replicas would race on session-id files and corrupt state. The chart enforces replicas: 1 + strategy: Recreate.
  • No HA postgres. The sidecar is a single-instance StatefulSet. Use a managed PG (postgres.enabled=false) for production HA.
  • Single image only. The chart deploys siamakerlab/vibe-coder-server. There is no KVM / privileged emulator variant to deploy.
  • No native PSP/PodSecurity policy stance. Operators with a strict cluster baseline should add securityContext overrides via a values override file.

Upgrade

helm upgrade vibe ./helm/vibe-coder-server \
  --reuse-values \
  --set image.tag=0.48.0

strategy: Recreate means there's a short downtime during pod swap (PVC is single-attach). For zero-downtime upgrades you'd need to drain → backup → restart manually — not currently automated.

Related

Clone this wiki locally