Skip to content

πŸ™Œ OpenHands: AI-Driven Development

feat(helm): add Helm chart for StatefulSet deployment (#1641)

Robert Brennan30af61735c07
diff --git a/helm/agent-canvas/.helmignore b/helm/agent-canvas/.helmignore
new file mode 100644
index 0000000000..4275a16bb0
--- /dev/null
+++ b/helm/agent-canvas/.helmignore
@@ -0,0 +1,18 @@
+# Patterns to ignore when packaging Helm charts.
+.DS_Store
+.git/
+.gitignore
+.bzr/
+.hg/
+.svn/
+*.swp
+*.tmp
+*.orig
+*.bak
+# CI / test
+.github/
+.circleci/
+.travis.yml
+# Editor
+.idea/
+.vscode/
diff --git a/helm/agent-canvas/Chart.yaml b/helm/agent-canvas/Chart.yaml
new file mode 100644
index 0000000000..0856cbd064
--- /dev/null
+++ b/helm/agent-canvas/Chart.yaml
@@ -0,0 +1,26 @@
+apiVersion: v2
+name: agent-canvas
+description: |
+ Helm chart for running the OpenHands agent-canvas all-in-one image
+ (frontend + agent-server + automation) as a StatefulSet with persistent
+ storage, ingress, and optional cluster RBAC.
+type: application
+# Chart-level version. Bump on chart changes.
+version: 0.1.0
+# Default appVersion pins the published agent-canvas image tag from
+# config/defaults.json (`versions.agentCanvas`). Override via
+# `--set image.tag=...` to pull a different build (e.g. `main`, `latest`,
+# or a `sha-<git-sha>` tag).
+appVersion: "1.2.0"
+kubeVersion: ">=1.24.0-0"
+home: https://github.com/OpenHands/agent-canvas
+sources:
+ - https://github.com/OpenHands/agent-canvas
+keywords:
+ - openhands
+ - agent
+ - ai
+ - agent-canvas
+maintainers:
+ - name: OpenHands
+ url: https://github.com/OpenHands
diff --git a/helm/agent-canvas/README.md b/helm/agent-canvas/README.md
new file mode 100644
index 0000000000..0f0dba1627
--- /dev/null
+++ b/helm/agent-canvas/README.md
@@ -0,0 +1,214 @@
+# agent-canvas Helm chart
+
+Helm chart for running the [OpenHands agent-canvas](https://github.com/OpenHands/agent-canvas)
+all-in-one image (frontend + agent-server + automation) on Kubernetes as a
+`StatefulSet` with persistent storage, an `Ingress`, and optional in-cluster
+RBAC.
+
+> [!WARNING]
+> This Helm chart is experimental. Agent Canvas is an unauthenticated, single-tenant application. This helm chart doesn't address scale or zero-downtime deployments.
+
+## When to use this
+
+This chart turns a Kubernetes cluster into a shared, always-on Agent Canvas
+backend: one pod running the UI, agent-server, and automation stack, with a
+PVC that survives pod restarts and image upgrades. It's a good fit when you
+want:
+
+- **A self-hosted, persistent backend** instead of the laptop-friendly Docker
+ setup β€” so conversations, secrets, and the automation SQLite DB persist
+ across restarts without you managing the volume by hand.
+- **An internal "vibecoding" platform.** With [RBAC enabled](#rbac), give the
+ agent a skill that teaches it to deploy the small web apps it builds
+ straight into the cluster. From that point on, anyone with access to the
+ Agent Canvas UI can build and ship code into the cluster β€” and save it to
+ GitHub β€” with just a prompt. No pipelines, no manual `kubectl`, no
+ hand-written manifests.
+
+Put it behind an authenticated ingress before exposing it to the internet (see
+the [Security](#security) notes).
+
+## Relationship to OpenHands Enterprise
+
+Agent Canvas is an **unauthenticated, single-tenant** application. This chart
+runs exactly that: **one** shared instance where all agents are comingled on
+the same pod and PVC, with no built-in auth, RBAC for users, or tenant
+isolation. It's well suited to a single team or individual running their own
+backend.
+
+[OpenHands Enterprise (OHE)](https://www.all-hands.ai/enterprise) is the
+productized upgrade path when you need a hardened, multi-user deployment. OHE
+adds:
+
+- **Authentication** (SSO / SAML / OIDC) so users must log in.
+- **Role-based access control** over who can run agents and manage the
+ deployment.
+- **Multi-tenancy** so different teams get isolated spaces.
+- **Isolated agent sandboxes** β€” each agent run gets its own container rather
+ than every agent sharing the pod's filesystem.
+
+Use this chart for self-hosted, single-tenant setups; reach for OHE when you
+need authentication, multi-tenancy, or isolated agent execution.
+
+## TL;DR
+
+```bash
+helm install agent-canvas ./helm/agent-canvas
+```
+
+## What gets deployed
+
+| Resource | Purpose |
+| ----------------------------------- | ---------------------------------------------------------------------------------- |
+| `StatefulSet` | Single-replica pod running the all-in-one image (frontend + agent-server + automation). |
+| `PersistentVolumeClaim` (per pod) | Backs `~/.openhands` and `~/workspace` (both mounted from the same PVC via `subPath`): settings, encrypted secrets, conversation history, automation SQLite DB, cloned repos, generated files. |
+| `Service` (`ClusterIP` by default) | Cluster-internal endpoint on port 8000. |
+| `Service` (headless) | Required by the `StatefulSet` for stable pod DNS. |
+| `ServiceAccount` | Stable identity the pod runs under. Bindings depend on `rbac.*`. |
+| `Ingress` (optional) | External HTTP(S) entry point with the usual class/annotations/TLS knobs. |
+| `RoleBinding` (per namespace) | When `rbac.enabled=true`, one per entry in `rbac.namespaces`, bound to the built-in `admin` ClusterRole. |
+| `ClusterRoleBinding` (optional) | When `rbac.clusterAdmin=true`, binds the SA to `cluster-admin` cluster-wide. |
+
+## Persistence
+
+The chart provisions **one** PVC and mounts it at multiple well-known
+subdirectories of the openhands user's HOME (`/home/openhands`) via
+`subPath`. That preserves the pristine home directory the base image
+ships (dotfiles like `~/.bashrc` and `~/.profile`) while persisting the
+directories that actually contain state:
+
+- `~/.openhands` β€” agent-server settings, encrypted secrets,
+ conversation history and event stores, automation SQLite database
+ (unless `config.automationDbUrl` is set), auto-generated
+ `OH_SECRET_KEY`, session API key
+- `~/workspace` β€” the agent's default working directory: cloned repos,
+ worktrees, anything the agent writes when it treats `~` as the
+ workspace root
+
+Both paths share the same underlying disk. Add more entries to
+`persistence.mounts` if you want other subtrees persisted (e.g.
+`~/.cache`, `~/.config`).
+
+The pod runs as `openhands` (UID 10001) from the upstream image;
+`podSecurityContext.fsGroup=10001` makes the kubelet chown the PVC
+so that user can write to it.
+
+Point at an existing PVC with `persistence.existingClaim=<name>` if you
+manage the volume out of band; otherwise the chart uses the
+`StatefulSet`'s `volumeClaimTemplates` (recommended β€” data survives pod
+rescheduling and image upgrades).
+
+## RBAC
+
+RBAC is **off by default** β€” the pod runs under its own ServiceAccount
+but has no in-cluster permissions.
+
+Two independent switches:
+
+```yaml
+rbac:
+ enabled: true
+ # Full access to all resources in these namespaces (bound to the
+ # built-in `admin` ClusterRole via one RoleBinding per namespace).
+ namespaces:
+ - default
+ - agent-sandbox
+ # Optionally grant cluster-admin. OFF by default. Very broad β€” enable
+ # only when the agent truly needs to manage the whole cluster.
+ clusterAdmin: false
+```
+
+- `rbac.namespaces` creates one `RoleBinding` per namespace, referencing
+ the built-in `admin` ClusterRole. Those namespaces must already exist
+ in the cluster.
+- `rbac.clusterAdmin=true` creates an additional `ClusterRoleBinding` to
+ `cluster-admin`. This overrides / supersedes any per-namespace grant.
+
+## Ingress
+
+Standard knobs:
+
+```yaml
+ingress:
+ enabled: true
+ className: nginx
+ annotations:
+ nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
+ nginx.ingress.kubernetes.io/proxy-body-size: "50m"
+ cert-manager.io/cluster-issuer: letsencrypt-prod
+ hosts:
+ - host: agent-canvas.example.com
+ paths:
+ - path: /
+ pathType: Prefix
+ tls:
+ - hosts:
+ - agent-canvas.example.com
+ secretName: agent-canvas-tls
+```
+
+The agent-server uses WebSockets on `/sockets`, so long
+`proxy-read-timeout` / `proxy-send-timeout` values are recommended when
+using `ingress-nginx`. File uploads honor `proxy-body-size`.
+
+## Common overrides
+
+Provide an LLM key via secret:
+
+```yaml
+config:
+ extraEnv:
+ - name: LLM_MODEL
+ value: openhands/claude-sonnet-4-5-20250929
+ - name: LLM_API_KEY
+ valueFrom:
+ secretKeyRef:
+ name: my-llm-secret
+ key: api-key
+```
+
+Bring your own `OH_SECRET_KEY` (must match the value used to encrypt any
+existing PVC contents):
+
+```yaml
+secrets:
+ ohSecretKey:
+ existingSecret: agent-canvas-keys
+ key: ohSecretKey
+```
+
+Point automation at an external Postgres:
+
+```yaml
+config:
+ automationDbUrl: postgresql+asyncpg://user:pass@postgres/agentcanvas
+```
+
+## Security
+
+The agent server can read and write the pod filesystem, execute shell
+commands, and β€” when RBAC is enabled β€” mutate the Kubernetes cluster it runs
+in. There is no built-in authentication in Agent Canvas, so treat the release
+namespace as trusted infrastructure:
+
+- Put it behind an **authenticated** ingress (oauth2-proxy, Cloudflare Access,
+ tailscale-serve, etc.) before exposing it to the internet.
+- Avoid a bare `LoadBalancer` β€” the agent server accepts any request with the
+ right `LOCAL_BACKEND_API_KEY`, so exposing it directly means anyone who can
+ guess the key can drive the agent.
+- Only turn on `rbac.clusterAdmin` when you truly need cluster-wide access;
+ prefer scoping to specific namespaces via `rbac.namespaces`.
+
+For authentication, role-based access control, multi-tenancy, and isolated
+agent sandboxes, see [OpenHands Enterprise](#relationship-to-openhands-enterprise).
+
+## Uninstall
+
+```bash
+helm uninstall agent-canvas
+```
+
+By default the PVC created by `volumeClaimTemplates` is **retained**
+after uninstall β€” delete it manually if you want the data gone. Set
+`statefulSet.persistentVolumeClaimRetentionPolicy` (Kubernetes 1.27+) if
+you want the PVC lifecycle tied to the StatefulSet.
diff --git a/helm/agent-canvas/templates/NOTES.txt b/helm/agent-canvas/templates/NOTES.txt
new file mode 100644
index 0000000000..e81d002fdf
--- /dev/null
+++ b/helm/agent-canvas/templates/NOTES.txt
@@ -0,0 +1,55 @@
+agent-canvas has been installed as release {{ .Release.Name }} in namespace {{ .Release.Namespace }}.
+
+1. Wait for the StatefulSet pod to be ready:
+ kubectl -n {{ .Release.Namespace }} rollout status statefulset/{{ include "agent-canvas.fullname" . }}
+
+2. Access the UI:
+{{- if .Values.ingress.enabled }}
+ {{- range .Values.ingress.hosts }}
+ {{- $scheme := "http" -}}
+ {{- range $.Values.ingress.tls -}}
+ {{- if has $.host .hosts -}}
+ {{- $scheme = "https" -}}
+ {{- end -}}
+ {{- end }}
+ {{- range .paths }}
+ {{ $scheme }}://{{ $.host }}{{ .path }}
+ {{- end }}
+ {{- end }}
+{{- else if contains "NodePort" .Values.service.type }}
+ export NODE_PORT=$(kubectl -n {{ .Release.Namespace }} get svc {{ include "agent-canvas.fullname" . }} -o jsonpath='{.spec.ports[0].nodePort}')
+ export NODE_IP=$(kubectl get nodes -o jsonpath='{.items[0].status.addresses[0].address}')
+ echo "http://$NODE_IP:$NODE_PORT"
+{{- else if contains "LoadBalancer" .Values.service.type }}
+ Waiting for the LoadBalancer to be provisioned...
+ kubectl -n {{ .Release.Namespace }} get svc -w {{ include "agent-canvas.fullname" . }}
+{{- else }}
+ kubectl -n {{ .Release.Namespace }} port-forward svc/{{ include "agent-canvas.fullname" . }} 8000:{{ .Values.service.port }}
+ # Then open http://localhost:8000
+{{- end }}
+
+3. Retrieve the auto-generated session API key (needed for direct API calls):
+ kubectl -n {{ .Release.Namespace }} exec {{ include "agent-canvas.fullname" . }}-0 -- \
+ cat {{ .Values.persistence.mountPath }}/session-api-key.txt
+
+{{- if .Values.rbac.enabled }}
+
+4. RBAC is enabled for this release. The agent has been granted:
+ {{- if .Values.rbac.namespaces }}
+ - Admin access (built-in `admin` ClusterRole) in namespaces:
+ {{- range .Values.rbac.namespaces }}
+ * {{ . }}
+ {{- end }}
+ {{- end }}
+ {{- if .Values.rbac.clusterAdmin }}
+ - CLUSTER-ADMIN access to the entire cluster (via `cluster-admin`
+ ClusterRoleBinding). This is a very broad privilege β€” audit
+ access accordingly.
+ {{- end }}
+{{- else }}
+
+4. RBAC is disabled β€” the agent has no in-cluster permissions beyond
+ what the default ServiceAccount can do. Set `rbac.enabled=true` and
+ populate `rbac.namespaces` (and optionally `rbac.clusterAdmin=true`)
+ to grant it cluster access.
+{{- end }}
diff --git a/helm/agent-canvas/templates/_helpers.tpl b/helm/agent-canvas/templates/_helpers.tpl
new file mode 100644
index 0000000000..9e3dfd7dcd
--- /dev/null
+++ b/helm/agent-canvas/templates/_helpers.tpl
@@ -0,0 +1,102 @@
+{{/*
+Expand the name of the chart.
+*/}}
+{{- define "agent-canvas.name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" -}}
+{{- end -}}
+
+{{/*
+Create a fully qualified app name.
+*/}}
+{{- define "agent-canvas.fullname" -}}
+{{- if .Values.fullnameOverride -}}
+{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" -}}
+{{- else -}}
+{{- $name := default .Chart.Name .Values.nameOverride -}}
+{{- if contains $name .Release.Name -}}
+{{- .Release.Name | trunc 63 | trimSuffix "-" -}}
+{{- else -}}
+{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" -}}
+{{- end -}}
+{{- end -}}
+{{- end -}}
+
+{{- define "agent-canvas.chart" -}}
+{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" -}}
+{{- end -}}
+
+{{/*
+Common labels
+*/}}
+{{- define "agent-canvas.labels" -}}
+helm.sh/chart: {{ include "agent-canvas.chart" . }}
+{{ include "agent-canvas.selectorLabels" . }}
+{{- if .Chart.AppVersion }}
+app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
+{{- end }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+{{- end -}}
+
+{{/*
+Selector labels
+*/}}
+{{- define "agent-canvas.selectorLabels" -}}
+app.kubernetes.io/name: {{ include "agent-canvas.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+{{- end -}}
+
+{{/*
+Immutable labels β€” the subset of common labels that are safe to stamp
+into resource fields that Kubernetes rejects modifications to after
+creation. Excludes `helm.sh/chart` and `app.kubernetes.io/version`,
+both of which change whenever the chart version or appVersion is
+bumped.
+
+Use this (not `agent-canvas.labels`) inside anything under
+`StatefulSet.spec.volumeClaimTemplates[].metadata` β€” that subtree is
+immutable, and any diff there causes `helm upgrade` to fail with:
+
+ StatefulSet.apps ... is invalid: spec: Forbidden: updates to
+ statefulset spec for fields other than 'replicas', 'ordinals',
+ 'template', ... are forbidden
+
+Object-level `metadata.labels` (on the STS itself, Services, etc.)
+are mutable, so those keep the full `agent-canvas.labels` set.
+*/}}
+{{- define "agent-canvas.immutableLabels" -}}
+{{ include "agent-canvas.selectorLabels" . }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+{{- end -}}
+
+{{/*
+ServiceAccount name to use.
+*/}}
+{{- define "agent-canvas.serviceAccountName" -}}
+{{- if .Values.serviceAccount.create -}}
+{{- default (include "agent-canvas.fullname" .) .Values.serviceAccount.name -}}
+{{- else -}}
+{{- default "default" .Values.serviceAccount.name -}}
+{{- end -}}
+{{- end -}}
+
+{{/*
+Effective image reference.
+*/}}
+{{- define "agent-canvas.image" -}}
+{{- $tag := default .Chart.AppVersion .Values.image.tag -}}
+{{- printf "%s:%s" .Values.image.repository $tag -}}
+{{- end -}}
+
+{{/*
+PVC name β€” either the user-provided existing claim or the templated one
+that StatefulSet.volumeClaimTemplates generates as "<claimName>-<pod>".
+When existingClaim is set we mount it as a plain volume (not via
+volumeClaimTemplates), which is why the StatefulSet template branches.
+*/}}
+{{- define "agent-canvas.pvcClaimName" -}}
+{{- if .Values.persistence.existingClaim -}}
+{{- .Values.persistence.existingClaim -}}
+{{- else -}}
+data
+{{- end -}}
+{{- end -}}
diff --git a/helm/agent-canvas/templates/ingress.yaml b/helm/agent-canvas/templates/ingress.yaml
new file mode 100644
index 0000000000..973f3c0ac0
--- /dev/null
+++ b/helm/agent-canvas/templates/ingress.yaml
@@ -0,0 +1,48 @@
+{{- if .Values.ingress.enabled -}}
+{{- $fullName := include "agent-canvas.fullname" . -}}
+{{- $svcPort := .Values.service.port -}}
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+ name: {{ $fullName }}
+ namespace: {{ .Release.Namespace }}
+ labels:
+ {{- include "agent-canvas.labels" . | nindent 4 }}
+ {{- with .Values.ingress.annotations }}
+ annotations:
+ {{- toYaml . | nindent 4 }}
+ {{- end }}
+spec:
+ {{- if .Values.ingress.className }}
+ ingressClassName: {{ .Values.ingress.className }}
+ {{- end }}
+ {{- with .Values.ingress.tls }}
+ tls:
+ {{- range . }}
+ - hosts:
+ {{- range .hosts }}
+ - {{ . | quote }}
+ {{- end }}
+ {{- if .secretName }}
+ secretName: {{ .secretName }}
+ {{- end }}
+ {{- end }}
+ {{- end }}
+ rules:
+ {{- range .Values.ingress.hosts }}
+ - {{- if .host }}
+ host: {{ .host | quote }}
+ {{- end }}
+ http:
+ paths:
+ {{- range .paths }}
+ - path: {{ .path }}
+ pathType: {{ default "Prefix" .pathType }}
+ backend:
+ service:
+ name: {{ $fullName }}
+ port:
+ number: {{ $svcPort }}
+ {{- end }}
+ {{- end }}
+{{- end }}
diff --git a/helm/agent-canvas/templates/rbac.yaml b/helm/agent-canvas/templates/rbac.yaml
new file mode 100644
index 0000000000..fc94e2a2ca
--- /dev/null
+++ b/helm/agent-canvas/templates/rbac.yaml
@@ -0,0 +1,55 @@
+{{- if .Values.rbac.enabled -}}
+{{- $fullName := include "agent-canvas.fullname" . -}}
+{{- $saName := include "agent-canvas.serviceAccountName" . -}}
+{{- $saNs := .Release.Namespace -}}
+{{- $labels := include "agent-canvas.labels" . -}}
+
+{{/*
+ Per-namespace bindings. Each entry in .Values.rbac.namespaces gets a
+ RoleBinding to the built-in `admin` ClusterRole, granting the agent
+ full access to all resources in that namespace (create/update/delete
+ Pods, Deployments, Services, etc.) but NOT to cluster-scoped resources.
+*/}}
+{{- range $ns := .Values.rbac.namespaces }}
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+ name: {{ $fullName }}-admin
+ namespace: {{ $ns }}
+ labels:
+ {{- $labels | nindent 4 }}
+roleRef:
+ apiGroup: rbac.authorization.k8s.io
+ kind: ClusterRole
+ name: admin
+subjects:
+ - kind: ServiceAccount
+ name: {{ $saName }}
+ namespace: {{ $saNs }}
+{{- end }}
+
+{{/*
+ Optional cluster-admin binding. Off by default because it grants full
+ control of the whole cluster including all namespaces, nodes, CRDs,
+ RBAC itself, etc. Turn on with rbac.clusterAdmin=true only when the
+ agent legitimately needs to manage the entire cluster.
+*/}}
+{{- if .Values.rbac.clusterAdmin }}
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+ name: {{ $fullName }}-cluster-admin
+ labels:
+ {{- $labels | nindent 4 }}
+roleRef:
+ apiGroup: rbac.authorization.k8s.io
+ kind: ClusterRole
+ name: cluster-admin
+subjects:
+ - kind: ServiceAccount
+ name: {{ $saName }}
+ namespace: {{ $saNs }}
+{{- end }}
+{{- end }}
diff --git a/helm/agent-canvas/templates/service.yaml b/helm/agent-canvas/templates/service.yaml
new file mode 100644
index 0000000000..65414f0e5a
--- /dev/null
+++ b/helm/agent-canvas/templates/service.yaml
@@ -0,0 +1,43 @@
+apiVersion: v1
+kind: Service
+metadata:
+ name: {{ include "agent-canvas.fullname" . }}
+ namespace: {{ .Release.Namespace }}
+ labels:
+ {{- include "agent-canvas.labels" . | nindent 4 }}
+ {{- with .Values.service.annotations }}
+ annotations:
+ {{- toYaml . | nindent 4 }}
+ {{- end }}
+spec:
+ type: {{ .Values.service.type }}
+ ports:
+ - name: http
+ port: {{ .Values.service.port }}
+ targetPort: http
+ protocol: TCP
+ {{- if and (eq .Values.service.type "NodePort") .Values.service.nodePort }}
+ nodePort: {{ .Values.service.nodePort }}
+ {{- end }}
+ selector:
+ {{- include "agent-canvas.selectorLabels" . | nindent 4 }}
+---
+# Headless service required by the StatefulSet for stable network IDs.
+apiVersion: v1
+kind: Service
+metadata:
+ name: {{ include "agent-canvas.fullname" . }}-headless
+ namespace: {{ .Release.Namespace }}
+ labels:
+ {{- include "agent-canvas.labels" . | nindent 4 }}
+spec:
+ type: ClusterIP
+ clusterIP: None
+ publishNotReadyAddresses: true
+ ports:
+ - name: http
+ port: {{ .Values.service.port }}
+ targetPort: http
+ protocol: TCP
+ selector:
+ {{- include "agent-canvas.selectorLabels" . | nindent 4 }}
diff --git a/helm/agent-canvas/templates/serviceaccount.yaml b/helm/agent-canvas/templates/serviceaccount.yaml
new file mode 100644
index 0000000000..aad5925867
--- /dev/null
+++ b/helm/agent-canvas/templates/serviceaccount.yaml
@@ -0,0 +1,14 @@
+{{- if .Values.serviceAccount.create -}}
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+ name: {{ include "agent-canvas.serviceAccountName" . }}
+ namespace: {{ .Release.Namespace }}
+ labels:
+ {{- include "agent-canvas.labels" . | nindent 4 }}
+ {{- with .Values.serviceAccount.annotations }}
+ annotations:
+ {{- toYaml . | nindent 4 }}
+ {{- end }}
+automountServiceAccountToken: {{ .Values.serviceAccount.automountServiceAccountToken }}
+{{- end }}
diff --git a/helm/agent-canvas/templates/statefulset.yaml b/helm/agent-canvas/templates/statefulset.yaml
new file mode 100644
index 0000000000..261a70c0aa
--- /dev/null
+++ b/helm/agent-canvas/templates/statefulset.yaml
@@ -0,0 +1,174 @@
+{{- $fullName := include "agent-canvas.fullname" . -}}
+apiVersion: apps/v1
+kind: StatefulSet
+metadata:
+ name: {{ $fullName }}
+ namespace: {{ .Release.Namespace }}
+ labels:
+ {{- include "agent-canvas.labels" . | nindent 4 }}
+spec:
+ serviceName: {{ $fullName }}-headless
+ replicas: {{ .Values.replicaCount }}
+ podManagementPolicy: {{ .Values.statefulSet.podManagementPolicy }}
+ {{- with .Values.statefulSet.updateStrategy }}
+ updateStrategy:
+ {{- toYaml . | nindent 4 }}
+ {{- end }}
+ {{- with .Values.statefulSet.persistentVolumeClaimRetentionPolicy }}
+ persistentVolumeClaimRetentionPolicy:
+ {{- toYaml . | nindent 4 }}
+ {{- end }}
+ selector:
+ matchLabels:
+ {{- include "agent-canvas.selectorLabels" . | nindent 6 }}
+ template:
+ metadata:
+ labels:
+ {{- include "agent-canvas.selectorLabels" . | nindent 8 }}
+ {{- with .Values.podLabels }}
+ {{- toYaml . | nindent 8 }}
+ {{- end }}
+ {{- with .Values.podAnnotations }}
+ annotations:
+ {{- toYaml . | nindent 8 }}
+ {{- end }}
+ spec:
+ serviceAccountName: {{ include "agent-canvas.serviceAccountName" . }}
+ automountServiceAccountToken: {{ .Values.serviceAccount.automountServiceAccountToken }}
+ {{- with .Values.imagePullSecrets }}
+ imagePullSecrets:
+ {{- toYaml . | nindent 8 }}
+ {{- end }}
+ {{- with .Values.podSecurityContext }}
+ securityContext:
+ {{- toYaml . | nindent 8 }}
+ {{- end }}
+ containers:
+ - name: agent-canvas
+ image: {{ include "agent-canvas.image" . }}
+ imagePullPolicy: {{ .Values.image.pullPolicy }}
+ {{- with .Values.securityContext }}
+ securityContext:
+ {{- toYaml . | nindent 12 }}
+ {{- end }}
+ ports:
+ - name: http
+ containerPort: {{ .Values.config.port }}
+ protocol: TCP
+ env:
+ - name: PORT
+ value: {{ .Values.config.port | quote }}
+ - name: AGENT_SERVER_PORT
+ value: {{ .Values.config.agentServerPort | quote }}
+ - name: AUTOMATION_PORT
+ value: {{ .Values.config.automationPort | quote }}
+ {{- if .Values.config.automationDbUrl }}
+ - name: AUTOMATION_DB_URL
+ value: {{ .Values.config.automationDbUrl | quote }}
+ {{- end }}
+ {{- if .Values.secrets.ohSecretKey.existingSecret }}
+ - name: OH_SECRET_KEY
+ valueFrom:
+ secretKeyRef:
+ name: {{ .Values.secrets.ohSecretKey.existingSecret }}
+ key: {{ .Values.secrets.ohSecretKey.key }}
+ {{- end }}
+ {{- if .Values.secrets.sessionApiKey.existingSecret }}
+ - name: OH_SESSION_API_KEYS_0
+ valueFrom:
+ secretKeyRef:
+ name: {{ .Values.secrets.sessionApiKey.existingSecret }}
+ key: {{ .Values.secrets.sessionApiKey.key }}
+ {{- end }}
+ {{- with .Values.config.extraEnv }}
+ {{- toYaml . | nindent 12 }}
+ {{- end }}
+ {{- if .Values.probes.startup.enabled }}
+ startupProbe:
+ httpGet:
+ path: {{ .Values.probes.startup.path }}
+ port: http
+ periodSeconds: {{ .Values.probes.startup.periodSeconds }}
+ timeoutSeconds: {{ .Values.probes.startup.timeoutSeconds }}
+ failureThreshold: {{ .Values.probes.startup.failureThreshold }}
+ {{- end }}
+ {{- if .Values.probes.liveness.enabled }}
+ livenessProbe:
+ httpGet:
+ path: {{ .Values.probes.liveness.path }}
+ port: http
+ initialDelaySeconds: {{ .Values.probes.liveness.initialDelaySeconds }}
+ periodSeconds: {{ .Values.probes.liveness.periodSeconds }}
+ timeoutSeconds: {{ .Values.probes.liveness.timeoutSeconds }}
+ failureThreshold: {{ .Values.probes.liveness.failureThreshold }}
+ {{- end }}
+ {{- if .Values.probes.readiness.enabled }}
+ readinessProbe:
+ httpGet:
+ path: {{ .Values.probes.readiness.path }}
+ port: http
+ initialDelaySeconds: {{ .Values.probes.readiness.initialDelaySeconds }}
+ periodSeconds: {{ .Values.probes.readiness.periodSeconds }}
+ timeoutSeconds: {{ .Values.probes.readiness.timeoutSeconds }}
+ failureThreshold: {{ .Values.probes.readiness.failureThreshold }}
+ {{- end }}
+ {{- with .Values.resources }}
+ resources:
+ {{- toYaml . | nindent 12 }}
+ {{- end }}
+ {{- if .Values.persistence.enabled }}
+ volumeMounts:
+ {{- range .Values.persistence.mounts }}
+ - name: {{ include "agent-canvas.pvcClaimName" $ }}
+ mountPath: {{ .mountPath }}
+ {{- if .subPath }}
+ subPath: {{ .subPath }}
+ {{- end }}
+ {{- end }}
+ {{- end }}
+ {{- with .Values.nodeSelector }}
+ nodeSelector:
+ {{- toYaml . | nindent 8 }}
+ {{- end }}
+ {{- with .Values.tolerations }}
+ tolerations:
+ {{- toYaml . | nindent 8 }}
+ {{- end }}
+ {{- with .Values.affinity }}
+ affinity:
+ {{- toYaml . | nindent 8 }}
+ {{- end }}
+ {{- with .Values.topologySpreadConstraints }}
+ topologySpreadConstraints:
+ {{- toYaml . | nindent 8 }}
+ {{- end }}
+ {{- if and .Values.persistence.enabled .Values.persistence.existingClaim }}
+ volumes:
+ - name: {{ include "agent-canvas.pvcClaimName" . }}
+ persistentVolumeClaim:
+ claimName: {{ .Values.persistence.existingClaim }}
+ {{- end }}
+ {{- if and .Values.persistence.enabled (not .Values.persistence.existingClaim) }}
+ volumeClaimTemplates:
+ - metadata:
+ name: {{ include "agent-canvas.pvcClaimName" . }}
+ labels:
+ {{- /* MUST use immutableLabels here, not the full label set.
+ volumeClaimTemplates is under STS.spec (not spec.template)
+ and is rejected by the apiserver on any diff, including
+ label churn from `appVersion` / chart `version` bumps. */}}
+ {{- include "agent-canvas.immutableLabels" . | nindent 10 }}
+ {{- with .Values.persistence.annotations }}
+ annotations:
+ {{- toYaml . | nindent 10 }}
+ {{- end }}
+ spec:
+ accessModes:
+ {{- toYaml .Values.persistence.accessModes | nindent 10 }}
+ {{- if .Values.persistence.storageClassName }}
+ storageClassName: {{ .Values.persistence.storageClassName | quote }}
+ {{- end }}
+ resources:
+ requests:
+ storage: {{ .Values.persistence.size | quote }}
+ {{- end }}
diff --git a/helm/agent-canvas/values.yaml b/helm/agent-canvas/values.yaml
new file mode 100644
index 0000000000..6f9eb3376c
--- /dev/null
+++ b/helm/agent-canvas/values.yaml
@@ -0,0 +1,235 @@
+# Default values for agent-canvas.
+# This chart deploys the all-in-one agent-canvas image (frontend +
+# agent-server + automation) as a single-replica StatefulSet with a
+# PersistentVolumeClaim mounted at $HOME/.openhands.
+
+# -- Number of replicas. The all-in-one image stores conversation state,
+# settings, and the automation SQLite DB on a single PVC β€” keep this at 1
+# unless you point AUTOMATION_DB_URL at an external Postgres and are ready
+# to run the agent-server in a genuinely shareable mode.
+replicaCount: 1
+
+image:
+ repository: ghcr.io/openhands/agent-canvas
+ # Image tag is pinned to the chart's appVersion. Override with
+ # `--set image.tag=sha-<...>` when you need a specific build (e.g. a PR
+ # image or a hotfix that doesn't match the chart's appVersion).
+ # tag: ""
+ pullPolicy: IfNotPresent
+
+imagePullSecrets: []
+# - name: ghcr-pull-secret
+
+nameOverride: ""
+fullnameOverride: ""
+
+# ── ServiceAccount + RBAC ────────────────────────────────────────────────────
+# When rbac.enabled is true, the ServiceAccount gets permissions inside
+# the cluster. Two independent knobs:
+#
+# rbac.namespaces β€” list of namespaces where the SA is granted
+# full ("*") access to all resources via a
+# per-namespace RoleBinding to the cluster's
+# built-in `admin` ClusterRole.
+# rbac.clusterAdmin β€” if true, additionally bind the SA to the
+# built-in `cluster-admin` ClusterRole.
+# OFF by default.
+#
+# Leave rbac.enabled=false to run the agent with no cluster access at all
+# (the ServiceAccount is still created so pods run under a stable
+# identity, but no Role/ClusterRole bindings are created).
+serviceAccount:
+ create: true
+ name: ""
+ annotations: {}
+ automountServiceAccountToken: true
+
+rbac:
+ # Master switch for creating any RoleBinding / ClusterRoleBinding.
+ enabled: false
+ # Namespaces the agent-server is allowed to manage all resources in.
+ # Each entry produces a RoleBinding in that namespace binding this
+ # release's ServiceAccount to the built-in `admin` ClusterRole (full
+ # namespace-scoped access, but no cluster-wide privileges).
+ #
+ # Example:
+ # namespaces:
+ # - default
+ # - agent-sandbox
+ namespaces: []
+ # If true, additionally grant cluster-admin via a ClusterRoleBinding.
+ # This is a very broad privilege β€” off by default.
+ clusterAdmin: false
+
+# ── Service ──────────────────────────────────────────────────────────────────
+service:
+ type: ClusterIP
+ port: 8000
+ # nodePort: 30800 # only used when type is NodePort
+ annotations: {}
+
+# ── Ingress ──────────────────────────────────────────────────────────────────
+ingress:
+ enabled: false
+ className: ""
+ annotations: {}
+ # nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
+ # nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
+ # nginx.ingress.kubernetes.io/proxy-body-size: "50m"
+ # cert-manager.io/cluster-issuer: letsencrypt-prod
+ hosts:
+ - host: agent-canvas.local
+ paths:
+ - path: /
+ pathType: Prefix
+ tls: []
+ # - hosts:
+ # - agent-canvas.example.com
+ # secretName: agent-canvas-tls
+
+# ── Persistence ──────────────────────────────────────────────────────────────
+# The chart provisions ONE PVC and mounts it in the pod at multiple
+# well-known subdirectories of $HOME so those trees survive pod
+# restarts, rescheduling, and image upgrades β€” while leaving the rest
+# of $HOME untouched (the base image ships dotfiles like ~/.bashrc and
+# ~/.profile there that must not be shadowed).
+#
+# Defaults cover the two paths users care about:
+# * $HOME/.openhands β€” agent-server settings, encrypted secrets,
+# conversation history, event stores, automation SQLite DB (unless
+# AUTOMATION_DB_URL is overridden), session API key, OH_SECRET_KEY
+# * $HOME/workspace β€” the agent's default working directory: cloned
+# repos, worktrees, generated files, anything the agent writes when
+# it treats ~ as the workspace root
+#
+# The upstream agent-server image runs as `openhands` (UID 10001) with
+# HOME=/home/openhands. Add more entries to `mounts` if you want other
+# subtrees persisted (e.g. ~/.cache, ~/.config).
+persistence:
+ enabled: true
+ # List of paths inside $HOME to persist. Each entry becomes a
+ # volumeMount on the container backed by the same PVC via `subPath`,
+ # so multiple paths share the same disk. `mountPath` is the absolute
+ # path inside the container; `subPath` is a directory name inside
+ # the PVC (must be unique across entries and safe on ext4).
+ mounts:
+ - mountPath: /home/openhands/.openhands
+ subPath: openhands
+ - mountPath: /home/openhands/workspace
+ subPath: workspace
+ size: 20Gi
+ # storageClassName: "" # empty β†’ cluster default
+ accessModes:
+ - ReadWriteOnce
+ annotations: {}
+ # If you prefer to bring your own PVC (already existing in the
+ # namespace), set existingClaim to its name. That disables the
+ # StatefulSet volumeClaimTemplates path.
+ existingClaim: ""
+
+# ── Configuration ────────────────────────────────────────────────────────────
+config:
+ # Unified entry point port inside the container.
+ port: 8000
+ # Internal ports used by the entrypoint's process manager.
+ agentServerPort: 18000
+ automationPort: 18001
+ # Optional Postgres connection string for the automation backend.
+ # When empty, the entrypoint falls back to SQLite on the PVC.
+ # automationDbUrl: "postgresql+asyncpg://user:pass@host/db"
+ automationDbUrl: ""
+ # Extra environment variables to pass through to the container.
+ # Each entry is `{ name: ..., value: ... }` or `{ name: ..., valueFrom: ... }`.
+ extraEnv: []
+ # - name: LLM_MODEL
+ # value: "openhands/claude-sonnet-4-5-20250929"
+ # - name: LLM_API_KEY
+ # valueFrom:
+ # secretKeyRef:
+ # name: my-llm-secret
+ # key: api-key
+
+secrets:
+ # If provided, seed OH_SECRET_KEY (settings encryption) and the
+ # session API key from Kubernetes Secrets instead of letting the
+ # entrypoint auto-generate them on first boot.
+ # Auto-generation persists to the PVC, so leaving these empty is fine
+ # for most single-tenant deployments.
+ ohSecretKey:
+ existingSecret: ""
+ key: "ohSecretKey"
+ sessionApiKey:
+ existingSecret: ""
+ key: "sessionApiKey"
+
+# ── Pod-level knobs ──────────────────────────────────────────────────────────
+podAnnotations: {}
+podLabels: {}
+
+podSecurityContext:
+ # The upstream agent-server image runs as `openhands` (UID 10001).
+ # fsGroup 10001 makes the kubelet chown the PVC to that gid on mount
+ # so the process can write to it. runAsUser/runAsGroup are pinned to
+ # the same values as a belt-and-suspenders check against future image
+ # rebuilds β€” if the image's USER changes, override these to match.
+ fsGroup: 10001
+ runAsNonRoot: true
+ runAsUser: 10001
+ runAsGroup: 10001
+
+securityContext: {}
+ # capabilities:
+ # drop: [ALL]
+ # readOnlyRootFilesystem: false
+ # allowPrivilegeEscalation: false
+
+resources:
+ requests:
+ cpu: 500m
+ memory: 1Gi
+ limits:
+ cpu: "2"
+ memory: 4Gi
+
+nodeSelector: {}
+tolerations: []
+affinity: {}
+topologySpreadConstraints: []
+
+# Probes hit the unified entry point.
+probes:
+ liveness:
+ enabled: true
+ path: /alive
+ initialDelaySeconds: 30
+ periodSeconds: 30
+ timeoutSeconds: 5
+ failureThreshold: 5
+ readiness:
+ enabled: true
+ path: /alive
+ initialDelaySeconds: 10
+ periodSeconds: 10
+ timeoutSeconds: 5
+ failureThreshold: 3
+ startup:
+ enabled: true
+ path: /alive
+ periodSeconds: 5
+ timeoutSeconds: 5
+ # Allow up to 5 minutes for first-boot dependencies / DB migration.
+ failureThreshold: 60
+
+# StatefulSet-specific knobs.
+statefulSet:
+ # Whether the StatefulSet uses OrderedReady or Parallel pod management.
+ # OrderedReady is safer for stateful workloads; use Parallel only if
+ # you understand the implications.
+ podManagementPolicy: OrderedReady
+ # updateStrategy for rollouts.
+ updateStrategy:
+ type: RollingUpdate
+ # Retained volumes on scale-down/deletion. Kubernetes 1.27+.
+ # persistentVolumeClaimRetentionPolicy:
+ # whenDeleted: Retain
+ # whenScaled: Retain