OpenHands · jlav · Aug 21, 2026 · Aug 21, 2026 · Aug 21, 2026 · Aug 21, 2026
diff --git a/docs.json b/docs.json
@@ -539,7 +539,8 @@
           {
             "group": "VM Install",
             "pages": [
-              "enterprise/vm-install/admin-console-configuration"
+              "enterprise/vm-install/admin-console-configuration",
+              "enterprise/vm-install/scaling"
             ]
           },
           {

diff --git a/enterprise/vm-install/admin-console-configuration.mdx b/enterprise/vm-install/admin-console-configuration.mdx
@@ -36,14 +36,14 @@

 ### Recommended: Simple

 Use the default `Simple` mode unless your organization requires a custom hostname for each service.

 1. Leave `Hostname Configuration Mode` set to `Simple (default)`.
 2. Enter your `Base Domain`, such as `openhands.example.com`.

 Every hostname sits one subdomain under the base domain, so a single wildcard DNS record and TLS certificate for `*.openhands.example.com` cover all of them:

 | Service | Hostname |
 |---|---|
 | Admin Console | `admin.openhands.example.com:30000` |
 | OpenHands application | `app.openhands.example.com` |
@@ -54,7 +54,7 @@
 | Sandboxes | `<id>-runtime.openhands.example.com` |

 <Note>
  Installations created before the Simple layout run in `Legacy` mode, which nests some hostnames deeper (`auth.app.<base>`, `*.runtime.<base>`). Keep existing installs on Legacy; their certificates and OAuth callbacks were issued for those hostnames.
 </Note>

 <Accordion title="Customize every hostname">
@@ -62,19 +62,19 @@

  | Field | Description |
  |---|---|
  | `Application Hostname` | Hostname for the OpenHands application. |
  | `Analytics Hostname` | Hostname for the analytics service. |
  | `Authentication Hostname` | Hostname for Keycloak. |
  | `LLM Proxy Hostname` | Hostname for the bundled LiteLLM proxy. |
  | `Runtime API Hostname` | Hostname for the Runtime API. |
  | `Runtime Base Hostname` | Base hostname used to create sandbox routes. |

  You must create DNS records, issue certificates, and configure external OAuth and webhook callbacks for the complete custom hostname set.
 </Accordion>

 ### Additional CORS Origins

 `Additional Permitted CORS Origins` is optional in either hostname mode. Enter a comma-separated list of browser origins, including the scheme and host with no path or trailing slash. The OpenHands application origin is always allowed automatically.

 ## Certificate Configuration

@@ -99,7 +99,7 @@
 | `Google` | Google AI Studio API key, or Vertex AI project, location, service-account file, and model IDs |
 | `DeepSeek` | API key |
 | `Mistral AI` | API key |
 | `Azure` | Authentication method, endpoint, API version, deployment names, and either an API key or Microsoft Entra service-principal credentials |
 | `Groq` | API key |
 | `OpenRouter` | API key |
 | `AWS Bedrock` | Authentication method, AWS Region, model IDs, and optionally an access-key pair |
@@ -142,11 +142,11 @@

 ### Azure DevOps Authentication

 Configure the Microsoft Entra tenant, Azure DevOps organization, client ID, and client secret. See [Azure DevOps](/enterprise/integrations/azure-devops).

 ### Jira Data Center Integration

 Configure the Jira base URL, account-linking method, and either OAuth or service-account credentials. See [Jira Data Center](/enterprise/integrations/jira-data-center).

 ### GitHub Authentication

@@ -163,7 +163,7 @@

 ### GitLab Authentication

 Provide the GitLab host and OAuth client credentials. Leave the host at `gitlab.com` for GitLab SaaS, or enter the hostname of your self-managed GitLab instance.

 ### Slack

@@ -175,7 +175,7 @@

 | Field | Description |
 |---|---|
 | `SMTP Host` | SMTP server hostname. |
 | `SMTP Port` | SMTP server port. The default is `587`. |
 | `SMTP From Email` | Sender address for OpenHands notifications. |
 | `Use SMTP SSL` | Uses implicit TLS/SMTPS. |
@@ -195,7 +195,7 @@
 - SSL mode
 - Username and password
 - Whether OpenHands should create databases automatically
 - Database names for OpenHands, Keycloak, LiteLLM, Runtime API, and Automations

 See [External PostgreSQL](/enterprise/external-postgres) for version, encoding, privilege, and database requirements.

@@ -220,6 +220,7 @@
 | `Warm Runtime Count` | Number of ready sandboxes kept for faster conversation startup. Set to `0` for cold starts only. |
 | `Additional Host Path Mounts` | Host paths mounted into every sandbox, one per line as `host_path:container_path[:ro\|rw]`. |
 | `Enable /dev/kvm passthrough (QEMU/KVM)` | Makes host KVM acceleration available inside sandboxes. The node must expose `/dev/kvm`. |
+| `Run sandboxes on dedicated nodes` | Confines sandboxes to machines added with the `sandbox` role, and keeps the application off those machines. Requires at least one `sandbox` machine already joined. See [Scaling the Cluster](/enterprise/vm-install/scaling). |
 
 <Note>
   `Idle Time` and `Deletion Time` control when idle and paused conversations are
@@ -243,7 +244,7 @@
 |---|---|
 | `HTTP_PROXY` | Proxy URL for HTTP traffic. |
 | `HTTPS_PROXY` | Proxy URL for HTTPS traffic. |
 | `NO_PROXY` | Additional comma-separated hosts that bypass the proxy. OpenHands adds internal services and configured deployment hostnames automatically. |
 | `SSL Verification` | Verifies outbound TLS certificates. Keep enabled unless a trusted proxy configuration requires otherwise. |

 Prefer adding the proxy CA under `Additional Trusted CA Certificates` instead of disabling TLS verification.
@@ -264,11 +265,11 @@

 See [Analytics](/enterprise/analytics) for the complete setup and verification flow.

 ## Automations

 `Enable Automations` deploys the Automations UI and backend.

 If you use external PostgreSQL, create and grant access to the Automations database before enabling this option.

 ## Advanced Options

@@ -286,10 +287,10 @@

 ## Installer-Managed Secrets

 Replicated generates internal PostgreSQL, Redis, JWT, Keycloak, LiteLLM, sandbox, plugin-directory, and Automations secrets during installation. These values are intentionally hidden from the configuration screen.

 <Warning>
  Do not rotate installer-managed secrets manually unless OpenHands Support provides a component-specific procedure. In particular, changing the LiteLLM salt key makes provider credentials already stored by LiteLLM undecryptable.
 </Warning>

 ## Related Guides

diff --git a/enterprise/vm-install/scaling.mdx b/enterprise/vm-install/scaling.mdx
@@ -0,0 +1,96 @@
+---
+title: Scaling the Cluster
+description: Add machines to an OpenHands Enterprise VM deployment to increase capacity, and run sandboxes on dedicated machines.
+icon: server
+---
+
+An OpenHands Enterprise VM deployment starts as a single machine that runs everything: the OpenHands application, its supporting services, and the sandboxes where conversations execute. Add machines when you need more capacity.
+
+## Machine Roles
+
+When you add a machine, you choose the role it takes. The role determines what runs on it and cannot be changed afterward.
+
+| Role | Runs |
+|---|---|
+| `app` | The OpenHands application and its supporting services. |
+| `sandbox` | Sandboxes only. |
+
+## Recommended: Dedicated Sandbox Machines
+
+For production, run sandboxes on dedicated `sandbox` machines.
+
+Sandboxes are the most variable workload in a deployment. When sandboxes share a machine with the OpenHands application, a burst of conversations competes for the same CPU and memory the application needs to serve requests. Separating them means sandbox demand cannot degrade or take down the application.
+
+Dedicated sandbox machines also give you a dial for conversation capacity.
+
+## Before You Begin
+
+<Warning>
+  New machines must be able to reach the existing machines over your private network. If your environment restricts traffic between machines, open these ports first. A machine that cannot reach the others will appear to join successfully and then fail to run workloads.
+
+  Open in both directions between all machines:
+
+  - `2380/TCP`
+  - `4789/UDP`
+  - `6443/TCP`
+  - `9091/TCP`
+  - `9443/TCP`
+  - `10249/TCP`
+  - `10250/TCP`
+  - `10256/TCP`
+
+  A joining machine also needs to reach `30000/TCP` and `50000/TCP` on the existing machines.
+
+  Note that `4789` is UDP.
+</Warning>
+
+## Add a Machine
+
+<Steps>
+  <Step title="Start the process">
+    In the Admin Console, select `Cluster Management`, then `Add node`.
+  </Step>
+  <Step title="Choose the role">
+    Select `app` or `sandbox`. The role cannot be changed after the machine is added.
+  </Step>
+  <Step title="Run the commands on the new machine">
+    The Admin Console displays download, extraction, and join commands for the role you selected. Connect to the new machine and run them in order.
+  </Step>
+  <Step title="Confirm it joined">
+    Return to `Cluster Management` and wait for the new machine's status to become `Ready`.
+  </Step>
+</Steps>
+
+<Note>
+  You can select both `app` and `sandbox`, but this is not recommended. A machine with both roles runs the application and sandboxes together, which gives up the separation you are adding the machine for. When adding a sandbox machine, make sure `app` is unchecked.
+</Note>
+
+## Add Sandbox Capacity
+
+Add one or more machines with the `sandbox` role, then confine sandboxes to them.
+
+<Steps>
+  <Step title="Add a sandbox machine">
+    Follow [Add a Machine](#add-a-machine) and select the `sandbox` role. Wait for its status to become `Ready`.
+  </Step>
+  <Step title="Turn on dedicated sandboxes">
+    Open `Config`, find `Sandbox Configuration`, and enable `Run sandboxes on dedicated nodes`. Save and deploy the change.
+  </Step>
+</Steps>
+
+<Note>
+  You can enable `Run sandboxes on dedicated nodes` before adding a `sandbox` machine, but new conversations cannot start until one is `Ready`. A configuration check warns you if the setting is enabled while no sandbox machine exists.
+</Note>
+
+Conversations that were already running stay on their original machine and are cleaned up normally as they go idle. Only new conversations move to the sandbox machines, so the transition needs no downtime.
+
+To add more conversation capacity later, add another `sandbox` machine.
+
+## Add Application Capacity
+
+Add machines with the `app` role to increase capacity for the OpenHands application itself.
+
+## Related Guides
+
+- [Admin Console Configuration](/enterprise/vm-install/admin-console-configuration)
+- [Conversations and Sandboxes](/enterprise/conversations-and-sandboxes)