> ## Documentation Index
> Fetch the complete documentation index at: https://allhandsai-jl-vm-install-scaling.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Scaling the Cluster

> Add machines to an OpenHands Enterprise VM deployment to increase capacity, and run sandboxes on dedicated machines.

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)