Linux & Kubernetes

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

# Create namespace and secrets
kubectl create namespace helix
kubectl config set-context --current --namespace=helix
 
# Postgres credentials for the bundled Postgres pod (or an external instance).
kubectl create secret generic postgresql-auth-secret \
  --from-literal=username="helix" \
  --from-literal=password="$(openssl rand -hex 16)" \
  --from-literal=database="helix"
 
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"
 
kubectl create secret generic helix-license \
  --from-literal=license-key="<paste-your-license-key>"
 
# Encryption key for secrets at rest (PATs, SSH keys, OAuth tokens).
# Must be a 64-character hex string (32 bytes for AES-256-GCM). DO NOT
# rotate this once data has been written - rotating invalidates every
# stored secret.
kubectl create secret generic helix-encryption-key \
  --from-literal=encryption-key="$(openssl rand -hex 32)"
 
# Random token, used by the sandbox chart to auth back to the control plane.
kubectl create secret generic helix-runner-secrets \
  --from-literal=api-token="$(openssl rand -hex 32)"

# Production-ready configuration for helix-controlplane
# For more options: https://github.com/helixml/helix/blob/main/charts/helix-controlplane/values-example.yaml
 
global:
  # Public URL of your Helix deployment. Also injected into the desktop
  # sandbox containers as the URL their inner agent (Zed / Qwen Code)
  # uses to reach the control plane API. The default of
  # http://localhost:8080 is ONLY correct for a single-binary local
  # install - inside a Kubernetes cluster localhost resolves to the
  # sandbox pod itself and inference will fail with
  # "error sending request for url (http://localhost:8080/...)".
  #
  # In Kubernetes set this to either:
  #   - the cluster-internal service URL of the control plane, e.g.
  #     http://my-helix-controlplane.helix.svc.cluster.local
  #     (works for port-forward / private access)
  #   - or your public ingress hostname, e.g. https://helix.example.com
  serverUrl: http://my-helix-controlplane.helix.svc.cluster.local
 
# Leave image.tag unset so the chart uses its pinned appVersion.
# Do NOT set it to "latest" - no :latest tag is published to GHCR.
# To pin a specific release, use e.g. tag: "2.9.31".
 
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
    storageClass: ""
    annotations: {}
    accessModes:
      - ReadWriteOnce
 
controlplane:
  licenseKeyExistingSecret: "helix-license"
  licenseKeyExistingSecretKey: "license-key"
 
  runnerTokenExistingSecret: "helix-runner-secrets"
  runnerTokenExistingSecretKey: "api-token"
 
  # Encryption key for secrets at rest (PATs, SSH keys, OAuth tokens).
  # Required - the API will refuse to start without it. Generated above
  # via `openssl rand -hex 32`. Do not rotate after data is written.
  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"
 
  inference:
    defaultProvider: "helix"
 
  fineTuning:
    defaultProvider: "helix"
 
  # Configure at least one LLM provider. Without this, there will be
  # no models available after first login. Provide an API key inline,
  # or reference a Kubernetes secret via controlplane.providers.<name>.apiKeyExistingSecret.
  # providers:
  #   anthropic:
  #     apiKey: "sk-ant-..."
  #   openai:
  #     apiKey: "sk-..."
 
  # Extra environment variables injected into the control plane pod.
  # The control plane process is where settings like HELIX_ENCODER
  # are read and forwarded to inner desktop containers spawned for
  # spec task / Zed agent sessions.
  #
  # Example: opt into hardware H.264 video encoding on AMD GPUs
  # (requires Helix 2.10.0+; no-op on 2.9.x). Default auto-detect uses
  # software OpenH264 on AMD because of a historical gst-va crash on
  # older Mesa; this flag bypasses that skip.
  # extraEnv:
  #   - name: HELIX_ENCODER
  #     value: "vaapi"
 
persistence:
  enabled: true
  size: 100Gi
  storageClass: ""
  accessModes:
    - ReadWriteOnce
 
volumes:
  - name: data
 
postgresql:
  enabled: true
  auth:
    existingSecret: "postgresql-auth-secret"
    usernameKey: "username"
    passwordKey: "password"
    databaseKey: "database"
  persistence:
    enabled: true
    size: 10Gi
  resources:
    requests:
      cpu: "100m"
      memory: "256Mi"
    limits:
      memory: "1Gi"
 
tika:
  enabled: false
 
typesense:
  enabled: false

# Add Helix Helm repository
helm repo add helix https://charts.helixml.tech
helm repo update
 
# Install the control plane with your generated values.yaml and secrets.
# By default the chart uses its pinned appVersion. Do NOT set image.tag
# to "latest" - no :latest tag is published. To pin a specific release,
# add --set image.tag="<version>" (e.g. "2.9.31") or --version "<chart-version>".
helm upgrade --install my-helix-controlplane helix/helix-controlplane \
  -f values.yaml

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

controlplane:
  # ... your existing controlplane config ...
  providers:
    openai:
      existingSecret: "openai-api-key"
      existingSecretApiKeyKey: "api-key"
      # baseUrl: "https://api.openai.com/v1"   # override for Azure OpenAI or proxies
 
    anthropic:
      existingSecret: "anthropic-api-key"
      existingSecretApiKeyKey: "api-key"
 
    togetherai:
      existingSecret: "togetherai-api-key"
      existingSecretApiKeyKey: "api-key"
 
    vllm:
      # Self-hosted vLLM speaks the OpenAI API. Point at its cluster-internal service.
      # Most vLLM deployments need no API key; pass one via existingSecret if yours does.
      baseUrl: "http://my-vllm.vllm.svc.cluster.local:8000/v1"

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

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

# helix-controlplane values.yaml
global:
  extraEnv:
    - name: HTTPS_PROXY
      value: "http://proxy.internal:8080"
    - name: NO_PROXY
      value: "localhost,127.0.0.1,.svc,.cluster.local"
 
controlplane:
  extraEnv:
    - name: HELIX_VIDEO_MODE
      value: shm