Skip to main content
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. 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

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.

​
Add a Machine

1

Start the process

In the Admin Console, select Cluster Management, then Add node.
2

Choose the role

Select app or sandbox. The role cannot be changed after the machine is added.
3

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.
4

Confirm it joined

Return to Cluster Management and wait for the new machine’s status to become Ready.
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.

​
Add Sandbox Capacity

Add one or more machines with the sandbox role, then confine sandboxes to them.
1

Add a sandbox machine

Follow Add a Machine and select the sandbox role. Wait for its status to become Ready.
2

Turn on dedicated sandboxes

Open Config, find Sandbox Configuration, and enable Run sandboxes on dedicated nodes. Save and deploy the change.
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.
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.