oci://ghcr.io/openhands/helm-charts/openhands.
Get an Enterprise License
Request a 30-day trial on the OpenHands Pricing page, then copy your license key. You enter it in the setup wizard when you first sign in.Prepare Your Cluster
Review the prerequisites, then complete the guide for your Kubernetes provider before running the Helm commands: These guides cover cluster preparation and provider-specific Helm values. Return here once your cluster is ready, and merge the applicable provider values into your installation configuration. On AKS, keep the runc override file last in the Helm values arguments, as described in the AKS guide. For another Kubernetes provider, prepare a cluster that meets the prerequisites below, including storage, ingress and a supported sandbox runtime.Prerequisites
- A Kubernetes cluster with a default storage class and an ingress controller (see Resource Limits for sizing guidance)
- Helm v4 or later
kubectlaccess to the target cluster- Your license key (see Get an Enterprise License)
- LLM credentials from your chosen provider, for example an Anthropic API key from the Anthropic Console. For Azure models, see Azure LLM Gateway.
- DNS records you control, following the layout used throughout this guide
(with
openhands.example.comas the base domain):app.openhands.example.com(application),auth.openhands.example.com(login),runtime-api.openhands.example.com, and<id>-runtime.openhands.example.comfor the per-session sandboxes. Every hostname sits one label under the base domain, so a single wildcard record*.openhands.example.compointing at your cluster’s ingress covers all of them; see DNS and TLS. - A wildcard TLS certificate for
*.openhands.example.com, which you provide. - An authentication method for user login — GitLab, Bitbucket Data Center, and more are supported; this guide uses a GitHub App. See Creating a GitHub App.
Step 1: Create the namespaces and secrets
We recommend running agent sandboxes in a namespace separate from the application. Sandboxes run agent-authored code, so a dedicated namespace keeps them isolated from the application, database, and secrets. Create both namespaces now:openhands namespace:
keys
directory:
Step 2: Configure values
Create avalues.yaml with your environment-specific configuration. The
minimum for a working installation covers application ingress and TLS,
user authentication, the runtime (sandbox) endpoints, conversation
storage, and your LLM provider. PostgreSQL and Redis run embedded in the
cluster; the bundled PostgreSQL needs a database name and database creation
turned on, both shown below (to use your own database instead, see
External PostgreSQL).
The example below uses Traefik, the chart’s default ingress class; set
ingress.class and the annotations to match your controller.
Chart The static frontend can load without a second API-key prompt; Enterprise
API requests still use the signed-in session. Later chart versions may
provide a working default UI without these overrides.
0.71.1 redirects signed-in users to /canvas but does not enable
that frontend by default. For this chart version, add the following to
values.yaml so the first conversation can start:Step 3: Install
Replace<chart-version> with a stable version from the
chart package,
or the version your provider guide supports. Check its values before installing. Version-specific notes on this page apply only
to the versions they name.
On AKS, append
--values values-aks-runc.yaml after --values values.yaml
in the command below. Keep the runc file last, after any feature overlays, on
every install and upgrade. See Azure AKS.Step 4: Validate the installation
The chart ships preflight checks that validate your cluster against the application’s requirements. Run them with thepreflight CLI:
- Open
https://app.openhands.example.comand sign in through your configured identity provider. As the first user, complete the setup wizard and enter your license key. The conversation UI should load without an additional backend URL or API-key prompt. - Start a new conversation and ask the agent to run
pwd. Confirm a sandbox starts inopenhands-runtimes, the command returns a path, and the agent gives a completed reply. - If the conversation cannot start, use the first-conversation checks before changing the deployment.
On chart
0.71.1, a fresh user’s selected Default LLM profile may not
match LITELLM_DEFAULT_MODEL. If the first request reports an invalid proxy
token or model, inspect the selected profile and the bundled LiteLLM model
list using the troubleshooting checks. Do not enter an infrastructure API key
into the browser to work around this error.Next Steps
The install above is a minimal working baseline. Features and tuning are values overrides on the same release — edit yourvalues.yaml and apply with
helm upgrade using the chart URL from Step 3 and --version <chart-version>
for your chosen upgrade version. Preserve all provider-specific values; on AKS, pass --values values-aks-runc.yaml last, after the base values
and any feature overlays.
Azure LLM Gateway
Configure Azure OpenAI and Azure AI Foundry model routes.
Resource Limits
Size memory, CPU, and replicas for production workloads.
External PostgreSQL
Use your own PostgreSQL instead of the embedded instance.
Analytics
Enable conversation analytics with Laminar.
Google Models
Configure Vertex AI or Gemini API routes in the bundled gateway.
Automations
Run scheduled or event-triggered tasks on a Helm installation.
AWS Bedrock
Route models through the bundled gateway using an IAM role on EKS.
Plugin Marketplace
Offer curated plugins to your users.
Troubleshooting
For a guided diagnostic workflow and a map of OHE components, see Troubleshooting.Generate a support bundle
If something isn’t working, generate a support bundle with thesupport-bundle CLI.
It discovers the diagnostic specs that ship with the chart and collects logs,
resource states, and health checks from the installation:

