DNS and TLS

Automate DNS records and TLS certificates with external-dns and cert-manager

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.openhands.example.com	Login (Keycloak)
runtime-api.openhands.example.com	Runtime API
<id>-runtime.openhands.example.com	Per-session sandboxes

All of these must resolve to your ingress load balancer. Every hostname sits one label under the base domain, so a single wildcard DNS record and certificate for *.openhands.example.com cover everything, including the dynamically named sandboxes.

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 wildcard certificates.

1. Install cert-manager

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

2. 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: [e-mail]
       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.

3. Request a wildcard certificate

   A single wildcard covers every hostname. 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: openhands-wildcard
     namespace: openhands
   spec:
     secretName: openhands-wildcard-tls
     issuerRef:
       name: letsencrypt-prod
       kind: ClusterIssuer
     dnsNames:
       - "*.openhands.example.com"
   

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 single wildcard record *.openhands.example.com pointing to your ingress load balancer (typically a CNAME to the load balancer’s hostname, or a cloud DNS alias).

TLS: obtain a certificate with a *.openhands.example.com SAN and load it into the ingress controller as a Kubernetes TLS secret.

If you can’t use a wildcard certificate, obtain one with SANs for the app, auth, and runtime-api hostnames plus runtime.openhands.example.com, and set runtime-api.env.RUNTIME_ROUTING_MODE: "path" in your Helm values so sandboxes are served under runtime.openhands.example.com/<id> instead of their own hostnames.

Next Steps

Installing Sysbox

Install the sandbox runtime on your sandbox nodes.

Install with Helm

Deploy OpenHands once the cluster is ready.