Skip to main content
Check out our Resourcing Guide before getting started.

​
Guide

The Onyx Helm chart packages all the required services (API, web, PostgreSQL, Vespa, etc.) into a single deployment. By default, persistent volumes will be created for stateful services (e.g. PostgreSQL, Vespa).
1

Add the Onyx Helm repository

helm repo add onyx https://onyx-dot-app.github.io/onyx/
helm repo update
helm search repo onyx
2

Install Onyx

Install into its own namespace (recommended):
kubectl create namespace onyx
helm install onyx onyx/onyx -n onyx
This will pull the latest Onyx chart and deploy all dependencies.
3

Verify the installation

helm list -n onyx
kubectl get pods -n onyx
Wait until all pods are in a Running state before accessing Onyx.
4

Access Onyx

By default, the chart exposes Onyx via a Kubernetes Service. For local testing, you can port-forward:
kubectl -n onyx port-forward service/onyx-nginx 8080:80
Then open http://localhost:8080.
5

Configure Onyx

Configure your deployment by modifying the values.yaml file in the onyx/deployment/helm/charts/onyx directory.You’ll need to restart Onyx after changing any values.yaml variables.
helm upgrade onyx onyx/onyx -n onyx -f deployment/helm/charts/onyx/values.yaml
See the Helm chart README for advanced options such as running as non-root and testing with Kind.

​
Enabling Onyx Craft

Onyx Craft can run on Helm deployments with the Kubernetes sandbox backend. Requirements:
  • Kubernetes >=1.33.
  • configMap.ENABLE_CRAFT=true.
  • configMap.SANDBOX_API_SERVER_URL set to a URL reachable from sandbox pods.
  • configMap.SANDBOX_BACKEND=kubernetes or left unset so the backend default remains Kubernetes.
  • auth.sandboxPushSecret.enabled=true.
  • A supported LLM provider: Anthropic, OpenAI, or OpenRouter.
Example values: 
configMap:
  ENABLE_CRAFT: "true"
  SANDBOX_BACKEND: "kubernetes"
  SANDBOX_API_SERVER_URL: "https://onyx.your-org.example"

auth:
  sandboxPushSecret:
    enabled: true
The Helm chart also renders the sandbox namespace, sandbox RBAC, sandbox pod template, sandbox proxy, and scheduled-task worker configuration used by Craft.
The Helm chart does not support the Docker sandbox backend. Docker sandboxes are for Docker Compose deployments.
Read the Craft deployment guide for the full operator checklist.

​
Next Steps

Configure Authentication

Set up authentication for your Onyx deployment with OAuth, OIDC, or SAML.

More Onyx Configuration Options

Learn about all available configuration options for your Onyx deployment.