Overview
What gets installed and how: Helm or Argo CD.
Harthelm is one Helm chart with no CRDs. Everything it keeps lives in PostgreSQL; Kubernetes holds only objects that core derives from that state, so the platform database (plus its master key) is all you need to back up.
What gets installed
In the release namespace, conventionally harthelm-system:
| Piece | What |
|---|---|
| core | Deployment <release>-core: the API and console, the internal port for the routers and workspace agents, the git proxy and metrics. It migrates the database at start; one replica leads the background jobs. |
| router | Deployment <release>-router, 2 replicas: serves every workspace host (<id>-<port>.<workspace domain>, ide-<id>.<workspace domain>) and the custom domains, and wakes sleeping workspaces. |
| platform database | A CloudNativePG Cluster <release>-db (bundled mode), or your own PostgreSQL (external mode). |
| edge | Ingresses or HTTPRoutes for the console host and *.<workspace domain>, optionally cert-manager Certificates. |
| security | ServiceAccounts, ClusterRoles, a Role, the admission guard and a NetworkPolicy for every pod. |
| jobs | The preflight Job (before every install and upgrade), the pre-upgrade dump, the nightly backup CronJob, optionally the workspace archive receiver. |
At runtime core creates one namespace per team, rg-<team id>, labelled harthelm.dev/managed=true, with its quota,
LimitRange, NetworkPolicies and the objects of the team's workspaces and services.
The images
A release is five images, all with the same version as the chart and pinned by digest:
| Image | Runs |
|---|---|
harthelm | core, the router and the jobs |
harthelm-agent | inside every workspace pod |
harthelm-tools | backups (pg_dump 18) |
harthelm-ide | the workspace IDE: code-server on Ubuntu 26.04 with Nix, mise and hart |
harthelm-base | services that name no image of their own |
The chart, the images and hart share one version number. Each release also attaches images.txt (every image the
chart can render, with its digest) and mirror.sh for air-gapped installs.
Helm or Argo CD
Both work with the same chart and values; the chart carries the hook annotations for both. Use Helm when a person installs and upgrades; use Argo CD when the values live in Git. The differences are in Install with Argo CD.
The chart's location
Releases are not published to a public registry yet. This documentation writes the chart as
oci://<your registry>/charts/harthelm: replace <your registry> with the registry you got the chart from.
The path through this section
Install
Install with Helm, then the track for your cluster: on-premises, EKS, AKS, GKE or air-gapped.
Configure
Configuration maps every topic to its values.