DNS and TLS

OpenHands needs DNS records and TLS certificates for its hostnames. We recommend automating both with external-dns and cert-manager, which run on any Kubernetes distribution and support the major cloud DNS providers. If you can’t run them, provision the records and certificates by hand, see Manual Setup.

Hostnames

OpenHands serves these hostnames, using openhands.example.com as the base domain (matching the Helm install):

Hostname	Purpose
`app.openhands.example.com`	Application
`auth.app.openhands.example.com`	Login (Keycloak)
`runtime-api.openhands.example.com`	Runtime API
`*.runtime.openhands.example.com`	Per-session sandboxes

All of these must resolve to your ingress load balancer. The sandbox entry must be a wildcard because each session gets its own subdomain.

external-dns

external-dns watches your Ingresses and Services and creates the matching DNS records automatically.

Install it from its Helm chart.
Set provider to your DNS provider and grant it access to your zone (the access mechanism is provider-specific).
Recommended settings:

provider:
  name: aws                   # or google, azure, cloudflare, ...
policy: upsert-only           # only ever create/update, never delete
registry: txt
txtOwnerId: openhands
domainFilters:
  - openhands.example.com     # only manage names under your base domain

With upsert-only and a TXT registry, external-dns only ever touches records it created.

cert-manager

cert-manager issues and renews certificates from Let’s Encrypt. Use the DNS-01 challenge, the only one that can issue the wildcard certificate the sandbox hostnames need.

Install cert-manager

Install it from its Helm chart, and grant it access to your DNS provider so it can solve DNS-01 challenges.

Create a ClusterIssuer

The solvers block is specific to your DNS provider. The Route 53 solver is shown here.

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: you@example.com
    privateKeySecretRef:
      name: letsencrypt-prod
    solvers:
      - dns01:
          route53:                 # swap for cloudDNS, azureDNS, cloudflare, ...
            hostedZoneID: <your-zone-id>

Start with the staging server (https://acme-staging-v02.api.letsencrypt.org/directory) while you get the setup working (generous rate limits), then switch to production.

Request a wildcard certificate

A single wildcard covers every sandbox host. With Traefik, serve it as the default TLSStore so no per-ingress TLS config is needed.

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: runtime-wildcard
  namespace: openhands
spec:
  secretName: runtime-wildcard-tls
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer
  dnsNames:
    - "*.runtime.openhands.example.com"

Issue certificates for the app, auth, and runtime-api hosts the same way.

Manual Setup

If you don’t run external-dns and cert-manager, provision these by hand and point the ingress controller at them. DNS: create a record for each hostname in the table above, all pointing to your ingress load balancer (typically a CNAME to the load balancer’s hostname, or a cloud DNS alias). The sandbox record must be the wildcard *.runtime.openhands.example.com. TLS: obtain certificates covering those hostnames and load them into the ingress controller as Kubernetes TLS secrets. A single wildcard isn’t enough, because the hostnames sit at different depths. You need:

*.runtime.openhands.example.com for the sandboxes, and
certificates for app.openhands.example.com, auth.app.openhands.example.com, and runtime-api.openhands.example.com (for example a *.openhands.example.com wildcard, which covers app and runtime-api, plus a certificate for auth.app.openhands.example.com).

OpenHands Enterprise

Integrations

K8s Install

Hostnames

external-dns

cert-manager

Manual Setup

Next Steps

Installing Sysbox

Install with Helm

​Hostnames

​external-dns

​cert-manager

​Manual Setup

​Next Steps

Installing Sysbox

Install with Helm

Hostnames

external-dns

cert-manager

Manual Setup

Next Steps