Skip to main content
OpenHands runs each agent session in a sandbox that uses Sysbox for isolation. This guide covers installing Sysbox.

​
Node Requirements

Sysbox nodes must:
  • Run a Sysbox-supported Linux distribution. Ubuntu is the most common and best-supported choice.
  • Have at least 4 vCPU and 4 GiB of memory.
  • Use containerd (the default on most managed distributions).
  • Run a Kubernetes version supported by Sysbox.
Run sandboxes on a dedicated node pool so these requirements (and the Sysbox install below) apply only to sandbox nodes, not the whole cluster.
On Amazon EKS, use Canonical’s EKS-optimized Ubuntu AMI for the sandbox node pool. The default Amazon Linux AMI isn’t supported. See Amazon EKS for the full node-pool setup.

​
Install Sysbox

Sysbox installs per node via the sysbox-deploy-k8s DaemonSet. It targets nodes labeled sysbox-install=yes, installs the runtime, and registers a sysbox-runc RuntimeClass.
1

Label the sandbox nodes

If your nodes autoscale, set this label on the group so every node it launches is labeled automatically.
2

Apply the installer

3

Confirm the RuntimeClass exists

The sysbox-runc RuntimeClass pins any pod that uses it to Sysbox nodes, so sandboxes only schedule where the runtime is installed.

​
Point OpenHands at Sysbox

Tell the runtime API to launch sandboxes with the Sysbox runtime class, and enable native user namespaces:

​
Verify

Start a conversation in OpenHands, then confirm the sandbox pod landed on a Sysbox node with the runtime class applied:
The output should be sysbox-runc.

​
Next Steps

DNS and TLS

Set up records and certificates for the OpenHands hostnames.

Install with Helm

Deploy OpenHands once the cluster is ready.