HelixML

Linux & Kubernetes

Install Helix on a Linux server or Kubernetes cluster, from licensing through first login.

Licensing

A license is required to run Helix on Linux or Kubernetes.

  • Developer license — for individuals, testing, and businesses with less than $10M annual revenue or fewer than 250 employees. Buy a developer license →
  • Enterprise license — for larger organizations with RBAC, SSO, SOC 2 Type II, and dedicated onboarding. Enterprise licensing →

Helix runs on any Kubernetes cluster — bare metal, Hetzner, OVH, AWS (EKS), GCP (GKE), or Azure (AKS). If you can run containers, you can run Helix.

For air-gapped deployments, see Sovereign Server.

Single Linux server

To install Helix on a Linux server with NVIDIA or AMD GPU support:

curl -sL -O https://get.helixml.tech/install.sh && bash install.sh

The installer detects your hardware and configures the sandbox automatically. On NVIDIA GPUs, hardware H.264 encoding is enabled automatically.

After installation, access Helix at http://localhost:8080. The first registered user becomes an admin.

Kubernetes install

Helm charts

Helix ships as two separate Helm charts:

ChartPurposeRequired?
helix-controlplaneAPI, UI, RAG, and orchestrationYes
helix-sandboxDocker-in-Docker host for agent desktop sessionsRecommended (required for spec tasks and coding agents)

Both charts are published to https://charts.helixml.tech.

Prerequisites

  • Kubernetes 1.28+. AKS/EKS/GKE Autopilot is not supported (sandbox requires privileged pods).
  • kubectl and Helm 3.x
  • A Helix license key from your account
  • A StorageClass that supports ReadWriteOnce PVCs
  • At least 8 vCPU / 24 GiB RAM for a minimal control-plane-only install (the Haystack embedding sidecar loads a ~4 GB model on first start)
  • At least one LLM provider (OpenAI, Anthropic, Together, or any OpenAI-compatible endpoint)

Cloud GPU quota

On fresh AWS/Azure/GCP accounts, GPU quota is 0 by default. Request quota before starting:

  • AWS: g5/p4d EC2 families per region
  • Azure: NVadsV710v5 (AMD) or NC*/ND* (NVIDIA) families + "Total Regional vCPUs"
  • GCP: nvidia-* GPU quotas per region

Step 1: Create namespace and secrets

kubectl create namespace helix
kubectl config set-context --current --namespace=helix
 
# Postgres credentials
kubectl create secret generic postgresql-auth-secret \
  --from-literal=username="helix" \
  --from-literal=password="$(openssl rand -hex 16)" \
  --from-literal=database="helix"
 
# pgvector credentials
kubectl create secret generic pgvector-auth-secret \
  --from-literal=username="postgres" \
  --from-literal=password="" \
  --from-literal=database="postgres"
 
kubectl create secret generic helix-pgvector-creds \
  --from-literal=dsn="postgresql://postgres:@my-helix-controlplane-pgvector:5432/postgres"
 
# License key
kubectl create secret generic helix-license \
  --from-literal=license-key="<your-license-key>"
 
# Encryption key — generate once, never rotate
kubectl create secret generic helix-encryption-key \
  --from-literal=encryption-key="$(openssl rand -hex 32)"
 
# Runner token — shared between control plane and sandbox
kubectl create secret generic helix-runner-secrets \
  --from-literal=api-token="$(openssl rand -hex 32)"

Step 2: Create values.yaml

global:
  # Public URL — must be reachable from inside the cluster for sandbox inference.
  # Do NOT use localhost here.
  serverUrl: http://my-helix-controlplane.helix.svc.cluster.local
 
searxng:
  enabled: true
 
chrome:
  enabled: true
 
pgvector:
  enabled: true
  auth:
    existingSecret: "pgvector-auth-secret"
    usernameKey: "username"
    passwordKey: "password"
    databaseKey: "database"
  persistence:
    enabled: true
    size: 50Gi
 
controlplane:
  licenseKeyExistingSecret: "helix-license"
  licenseKeyExistingSecretKey: "license-key"
  runnerTokenExistingSecret: "helix-runner-secrets"
  runnerTokenExistingSecretKey: "api-token"
  encryptionKeyExistingSecret: "helix-encryption-key"
  encryptionKeyExistingSecretKey: "encryption-key"
 
  admin:
    userSource: "env"
    userIds: "all"
 
  haystack:
    enabled: true
    existingSecret: "helix-pgvector-creds"
    existingSecretDsnKey: "dsn"
    embeddingsModel: "MrLight/dse-qwen2-2b-mrl-v1"
    embeddingsDim: "1536"
    chunkSize: "1000"
    chunkOverlap: "50"
    chunkUnit: "word"
 
  rag:
    defaultProvider: "haystack"
    embeddingsProvider: "helix"
 
  # Add at least one LLM provider
  # providers:
  #   anthropic:
  #     apiKey: "sk-ant-..."
  #   openai:
  #     apiKey: "sk-..."
 
persistence:
  enabled: true
  size: 100Gi
 
postgresql:
  enabled: true
  auth:
    existingSecret: "postgresql-auth-secret"
    usernameKey: "username"
    passwordKey: "password"
    databaseKey: "database"
  persistence:
    enabled: true
    size: 10Gi

Step 3: Add LLM provider secrets and configure them

kubectl create secret generic anthropic-api-key \
  --from-literal=api-key="sk-ant-..."

Add to controlplane.providers in your values.yaml:

controlplane:
  providers:
    anthropic:
      existingSecret: "anthropic-api-key"
      existingSecretApiKeyKey: "api-key"

See Configure LLM providers for all supported providers.

Step 4: Install the control plane

helm repo add helix https://charts.helixml.tech
helm repo update
 
helm upgrade --install my-helix-controlplane helix/helix-controlplane \
  -f values.yaml

First boot pulls the embedding model (~4 GB). Budget 5–10 minutes before the main pod becomes Ready.

Step 5: Install the sandbox chart

helm upgrade --install 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

Per-cloud override values are in the repository:

Step 6: Access the control plane

kubectl port-forward -n helix svc/my-helix-controlplane 8080:80

Open http://localhost:8080. The first registered user becomes an admin.

For production, configure an ingress with TLS and set global.serverUrl to the public HTTPS URL.

Environment variables and tuning

See Configuration reference for the full list of controlplane.extraEnv and sandbox.extraEnv variables (video streaming tuning, encoder selection, GPU render node, etc.).

External Postgres

The control plane chart can use a managed Postgres instead of the bundled one. However, the bundled pgvector sidecar requires the vectorchord and vectorchord-bm25 extensions, which managed services (Azure Flexible Server, RDS, Cloud SQL) don't provide out of the box. Keep pgvector.enabled: true and use the bundled pod for the vector index.

Upgrading

See Upgrade & migrate for the recommended procedure.