From a0e64cf29a095695d59868b3a734d75a18c71dd3 Mon Sep 17 00:00:00 2001 From: openhands Date: Mon, 4 May 2026 14:02:46 +0000 Subject: [PATCH 1/4] docs(enterprise): add path-based sandbox routing documentation Update the enterprise quick-start guide to document the path-based sandbox routing feature introduced in OpenHands-Cloud PR #563. Key changes: - Add tabbed DNS/TLS setup section covering both routing modes - Document path-based mode for environments without wildcard cert support - Update preflight DNS checks for both routing modes - Add Sandbox Routing Configuration section in Admin Console setup - Update requirements table to clarify routing mode dependencies Co-authored-by: openhands --- enterprise/quick-start.mdx | 97 +++++++++++++++++++++++++++++++------- 1 file changed, 80 insertions(+), 17 deletions(-) diff --git a/enterprise/quick-start.mdx b/enterprise/quick-start.mdx index 7c0f33e6..ba5d8362 100644 --- a/enterprise/quick-start.mdx +++ b/enterprise/quick-start.mdx @@ -115,21 +115,63 @@ You will need a VM to host OpenHands Enterprise. Choose one of the options below Once your VM is running, configure DNS and TLS before starting the installer. - **Create DNS A records** pointing to your VM's public IP address: - - | Record | Example | - |--------|---------| - | `` | `openhands.example.com` | - | `app.` | `app.openhands.example.com` | - | `auth.app.` | `auth.app.openhands.example.com` | - | `llm-proxy.` | `llm-proxy.openhands.example.com` | - | `runtime-api.` | `runtime-api.openhands.example.com` | - | `*.runtime.` | `*.runtime.openhands.example.com` | - - **Obtain a TLS certificate signed by a well-known certificate authority (CA) such as Let's Encrypt**, with SANs - (Subject Alternative Names) for all of the above domains, then copy the certificate - (`.pem` or `.crt`) and private key (`.pem` or `.key`) to the VM. Self-signed certificates - are not supported for the OpenHands application. + OpenHands supports two routing modes for sandbox (runtime) URLs. Choose the mode that + fits your infrastructure requirements: + + + + In subdomain mode, each sandbox is accessible at its own subdomain (e.g., `{sandbox_id}.runtime.example.com`). + This is the default and recommended mode for most deployments. + + **Create DNS A records** pointing to your VM's public IP address: + + | Record | Example | + |--------|---------| + | `` | `openhands.example.com` | + | `app.` | `app.openhands.example.com` | + | `auth.app.` | `auth.app.openhands.example.com` | + | `llm-proxy.` | `llm-proxy.openhands.example.com` | + | `runtime-api.` | `runtime-api.openhands.example.com` | + | `*.runtime.` | `*.runtime.openhands.example.com` | + + **Obtain a TLS certificate** with SANs (Subject Alternative Names) for all of the above domains, + including the **wildcard** `*.runtime.`. + + + + In path-based mode, all sandboxes share a single hostname with different path prefixes + (e.g., `runtime.example.com/{sandbox_id}`). Use this mode when: + + - Your certificate authority does not issue wildcard certificates + - Compliance requirements prohibit wildcard certificates + - Wildcard DNS records are not supported in your environment + + **Create DNS A records** pointing to your VM's public IP address: + + | Record | Example | + |--------|---------| + | `` | `openhands.example.com` | + | `app.` | `app.openhands.example.com` | + | `auth.app.` | `auth.app.openhands.example.com` | + | `llm-proxy.` | `llm-proxy.openhands.example.com` | + | `runtime-api.` | `runtime-api.openhands.example.com` | + | `runtime.` | `runtime.openhands.example.com` | + + **Note:** No wildcard DNS record is required. The `runtime.` record replaces `*.runtime.`. + + **Obtain a TLS certificate** with SANs for the above domains. **No wildcard SAN is required** — + only the base `runtime.` hostname. + + + You will configure **path-based routing mode** in the Admin Console under **Sandbox Configuration** + after installation. See [Sandbox Routing Configuration](#sandbox-routing-configuration) below. + + + + + **Certificate requirements:** Obtain a TLS certificate signed by a well-known certificate authority (CA) + such as Let's Encrypt, then copy the certificate (`.pem` or `.crt`) and private key (`.pem` or `.key`) + to the VM. Self-signed certificates are not supported for the OpenHands application. If you don't provide TLS certificates during installation, the Admin Console will use a @@ -177,7 +219,7 @@ done Expected: each hostname above resolves to your VM's public IP address. -Test that a runtime wildcard hostname resolves: +**For subdomain routing mode (default):** Test that a runtime wildcard hostname resolves: ```bash getent hosts "test.runtime.${BASE_DOMAIN}" || nslookup "test.runtime.${BASE_DOMAIN}" @@ -185,6 +227,14 @@ getent hosts "test.runtime.${BASE_DOMAIN}" || nslookup "test.runtime.${BASE_DOMA Expected: `test.runtime.${BASE_DOMAIN}` resolves to the same target as `${BASE_DOMAIN}`. +**For path-based routing mode:** Test that the runtime base hostname resolves: + +```bash +getent hosts "runtime.${BASE_DOMAIN}" || nslookup "runtime.${BASE_DOMAIN}" +``` + +Expected: `runtime.${BASE_DOMAIN}` resolves to the same target as `${BASE_DOMAIN}`. + ### Outbound connectivity checks ```bash @@ -226,7 +276,8 @@ If any check fails, stop and resolve before continuing: | `443/TCP` inbound | Primary HTTPS entrypoint for users and service hostnames | | `30000/TCP` inbound | Replicated/KOTS Admin Console for install and configuration | | `80/TCP` inbound | HTTP entrypoint used for ingress/redirect behavior | -| `*.runtime.` DNS + cert SAN | Runtime sandboxes are addressed by dynamic runtime-specific hostnames | +| `*.runtime.` DNS + cert SAN | Runtime sandboxes are addressed by dynamic runtime-specific hostnames (subdomain mode only) | +| `runtime.` DNS + cert SAN | Runtime base hostname for path-based sandbox routing (path-based mode only) | | `replicated.app`, `proxy.replicated.com` | Replicated control-plane/license/install paths | | `images.r9...`, `charts.r9...`, `updates.r9...`, `install.r9...` | Vendor distribution image/chart/update/install endpoints | | `traefik.github.io` | Embedded cluster ingress chart repository | @@ -330,6 +381,18 @@ You should now see the application configuration page. Enter your Anthropic API key from the [Anthropic Console](https://console.anthropic.com/). +### Sandbox Routing Configuration + +Under **Sandbox Configuration**, select your **Sandbox Routing Mode**: + +- **Subdomain** (default): Routes each sandbox at `{id}.runtime.`. Requires wildcard DNS and certificate. +- **Path-based**: Routes all sandboxes at `runtime./{id}`. No wildcard DNS or certificate required. + + + Select **Path-based** if your certificate authority does not issue wildcard certificates + or if your environment does not support wildcard DNS records. + + ### GitHub Authentication Enable GitHub Authentication in the Admin Console, then follow these steps to create and From 2e331c89dbfd921aea014f2f5b833cb120a53c1e Mon Sep 17 00:00:00 2001 From: openhands Date: Mon, 4 May 2026 14:13:17 +0000 Subject: [PATCH 2/4] docs(enterprise): add security callout for subdomain routing preference Add a warning callout explaining why subdomain-based routing is preferred from a security perspective - cookie isolation between sandboxes. Encourage customers to seek IT security exceptions. Co-authored-by: openhands --- enterprise/quick-start.mdx | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/enterprise/quick-start.mdx b/enterprise/quick-start.mdx index ba5d8362..0154ebcd 100644 --- a/enterprise/quick-start.mdx +++ b/enterprise/quick-start.mdx @@ -118,6 +118,23 @@ You will need a VM to host OpenHands Enterprise. Choose one of the options below OpenHands supports two routing modes for sandbox (runtime) URLs. Choose the mode that fits your infrastructure requirements: + + **Security Recommendation: Use Subdomain Routing When Possible** + + While many corporate IT security departments prefer to avoid wildcard certificates as a + general policy, **subdomain-based routing provides superior security isolation** for OpenHands. + + With subdomain routing, cookies issued by applications running in sandbox environments are + scoped to that specific sandbox's domain (e.g., `abc123.runtime.example.com`). This prevents + one sandbox from accessing cookies issued by another sandbox — an important security boundary + when running untrusted or user-provided code. + + Path-based routing shares a single domain across all sandboxes, which reduces this isolation. + + **We encourage customers to request an exception from corporate IT security** by explaining + this security benefit. Use subdomain routing wherever possible. + + In subdomain mode, each sandbox is accessible at its own subdomain (e.g., `{sandbox_id}.runtime.example.com`). From 8de3a2a57898cf7297edf32e33e048ebd77191a2 Mon Sep 17 00:00:00 2001 From: openhands Date: Mon, 4 May 2026 15:32:40 +0000 Subject: [PATCH 3/4] docs: update certificate requirements to reflect self-signed cert support Co-authored-by: openhands --- enterprise/quick-start.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/enterprise/quick-start.mdx b/enterprise/quick-start.mdx index 0154ebcd..596e5692 100644 --- a/enterprise/quick-start.mdx +++ b/enterprise/quick-start.mdx @@ -186,9 +186,9 @@ You will need a VM to host OpenHands Enterprise. Choose one of the options below - **Certificate requirements:** Obtain a TLS certificate signed by a well-known certificate authority (CA) - such as Let's Encrypt, then copy the certificate (`.pem` or `.crt`) and private key (`.pem` or `.key`) - to the VM. Self-signed certificates are not supported for the OpenHands application. + **Certificate requirements:** Copy your TLS certificate (`.pem` or `.crt`) and private key + (`.pem` or `.key`) to the VM. Both CA-signed certificates (e.g., from Let's Encrypt) and + self-signed certificates are supported. If you don't provide TLS certificates during installation, the Admin Console will use a From 1eccf68c4cb012121b27cac59c377873588d300f Mon Sep 17 00:00:00 2001 From: openhands Date: Mon, 4 May 2026 15:35:40 +0000 Subject: [PATCH 4/4] docs: move routing mode emphasis to front of table descriptions Co-authored-by: openhands --- enterprise/quick-start.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/enterprise/quick-start.mdx b/enterprise/quick-start.mdx index 596e5692..fcee9d44 100644 --- a/enterprise/quick-start.mdx +++ b/enterprise/quick-start.mdx @@ -293,8 +293,8 @@ If any check fails, stop and resolve before continuing: | `443/TCP` inbound | Primary HTTPS entrypoint for users and service hostnames | | `30000/TCP` inbound | Replicated/KOTS Admin Console for install and configuration | | `80/TCP` inbound | HTTP entrypoint used for ingress/redirect behavior | -| `*.runtime.` DNS + cert SAN | Runtime sandboxes are addressed by dynamic runtime-specific hostnames (subdomain mode only) | -| `runtime.` DNS + cert SAN | Runtime base hostname for path-based sandbox routing (path-based mode only) | +| `*.runtime.` DNS + cert SAN | **Subdomain mode only**: Runtime sandboxes are addressed by dynamic runtime-specific hostnames | +| `runtime.` DNS + cert SAN | **Path-based mode only**: Runtime base hostname for path-based sandbox routing | | `replicated.app`, `proxy.replicated.com` | Replicated control-plane/license/install paths | | `images.r9...`, `charts.r9...`, `updates.r9...`, `install.r9...` | Vendor distribution image/chart/update/install endpoints | | `traefik.github.io` | Embedded cluster ingress chart repository |