helm/agent-canvas/README.md

# agent-canvas Helm chart

Helm chart for running the [OpenHands agent-canvas](https://github.com/OpenHands/OpenHands)
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.