Upgrade and migrate

How to upgrade a self-hosted Helix deployment to a new version, and how to migrate data between environments.

Kubernetes upgrade

Helix uses rolling updates via Helm. The general procedure:

helm repo update
 
# Check the new chart version before applying
helm search repo helix/helix-controlplane --versions | head -5
 
# Upgrade the control plane
helm upgrade my-helix-controlplane helix/helix-controlplane \
  -f values.yaml
 
# Upgrade the sandbox
helm upgrade my-helix-sandbox helix/helix-sandbox \
  --namespace helix \
  --set sandbox.apiUrl="http://my-helix-controlplane.helix.svc.cluster.local" \
  --set sandbox.runnerTokenExistingSecret=helix-runner-secrets \
  --set sandbox.runnerTokenExistingSecretKey=api-token

The control plane runs database migrations automatically on startup (GORM AutoMigrate). If you prefer to run migrations out-of-band, set HELIX_SKIP_AUTOMIGRATE=1 and apply the schema changes before upgrading the pod.

Before upgrading

1. Check the release notes for breaking changes. Find them in the GitHub releases.
2. Back up Postgres before any major version upgrade (see Backup & restore below).
3. Check active sessions: active spec task sessions will be interrupted when the sandbox pod restarts. Schedule upgrades during low-activity periods.

Pinning a specific version

The chart's appVersion is pinned to a tested release. To pin to a specific Helix version:

helm upgrade my-helix-controlplane helix/helix-controlplane \
  -f values.yaml \
  --set image.tag="2.9.31"

Do not use image.tag=latest — no :latest tag is published.

Single-server upgrade

For installations using the install script (install.sh), pull the latest images and restart:

docker compose pull
docker compose up -d

The control plane runs database migrations automatically on startup.

Backup & restore

What to back up

The main Postgres database contains everything critical: users, organizations, projects, spec tasks, secrets, and repository connections. The vector database and file store can be rebuilt if lost.

Postgres backup

# Port-forward to the Postgres pod
kubectl port-forward svc/my-helix-controlplane-postgresql 5432:5432 &
 
# Dump
pg_dump -h localhost -U helix helix > helix_$(date +%Y%m%d).sql
 
# Restore (on a new cluster)
psql -h localhost -U helix helix < helix_20260610.sql

For production, use scheduled pg_dump to an S3 bucket or equivalent, or use your cloud provider's managed backup feature.

Restoring after disaster

1. Provision a new Kubernetes cluster
2. Create the same secrets (same encryption key — if you lose this, secrets at rest are unrecoverable)
3. Restore the Postgres dump
4. Run the Helm install
5. The control plane migrates the schema on startup; existing data is preserved

Migrating between environments

To move from one cluster to another (e.g., dev → prod):

1. pg_dump the source Postgres
2. Provision the target cluster with the same encryption key (it's needed to decrypt stored secrets)
3. Install Helix on the target with HELIX_SKIP_AUTOMIGRATE=1
4. Restore the dump to the target Postgres
5. Re-enable migrations (remove HELIX_SKIP_AUTOMIGRATE) and restart

Source control OAuth tokens and API keys were encrypted with the encryption key — they travel with the dump and work on the target as long as the encryption key matches.

Observability

See your platform logs:

docker compose logs -f            # single-server
kubectl logs -f deploy/my-helix-controlplane    # Kubernetes
kubectl logs -f deploy/my-helix-sandbox         # sandbox

Key log patterns to watch:

• schema migrated — database migration completed
• bootstrapping org — first-request org setup ran
• session started — agent session provisioned
• error starting session — sandbox session failed to start (check GPU resources)