OpenHands · dylan-openhands · Aug 10, 2026 · Aug 10, 2026
diff --git a/docs.json b/docs.json
@@ -486,6 +486,7 @@
             "pages": [
               "enterprise/index",
               "enterprise/enterprise-vs-oss",
+              "enterprise/sizing-guide",
               "enterprise/quick-start",
               "enterprise/custom-sandbox-image",
               "enterprise/docker-in-sandbox",

diff --git a/enterprise/index.mdx b/enterprise/index.mdx
@@ -30,7 +30,7 @@
  </Card>
  <Card title="Enterprise Security" icon="shield-halved">
    Deploy behind your firewall with your security policies. Fine-grained access
    control and auditability.
  </Card>
  <Card title="Cost Control" icon="coins">
    Use your own compute resources and LLM API keys. No per-seat licensing.
@@ -116,6 +116,7 @@
 
 ## Additional Resources
 
+- [Sizing Guide](/enterprise/sizing-guide) — Size a deployment from peak concurrent sandboxes
 - [OpenHands Documentation](/overview/introduction) — Learn how to use OpenHands
 - [SDK Documentation](/sdk/index) — Build custom agents with the OpenHands SDK
 - [Pricing](https://openhands.dev/pricing) — Compare all OpenHands plans
diff --git a/enterprise/k8s-install/index.mdx b/enterprise/k8s-install/index.mdx
@@ -1,7 +1,7 @@
 ---
 title: Kubernetes Installation
 description: Deploy OpenHands Enterprise into your own Kubernetes cluster using Helm
 icon: dharmachakra
 ---

 OpenHands Enterprise can be deployed into an existing Kubernetes cluster using Helm.
@@ -35,8 +35,8 @@
 |-----------|-------------|
 | **OpenHands Server** | Main application server handling UI, API, and agent orchestration |
 | **Runtime API** | Manages sandbox lifecycle: provisioning, scaling, and cleanup |
 | **Runtimes (Sandboxes)** | Isolated containers where agents execute code |
 | **Keycloak** | Identity and access management |
 | **LiteLLM Proxy** | Routes requests to your LLM provider(s) |
 | **PostgreSQL** | Persistent storage for application data |
 | **Redis** | Caching and session management |
@@ -50,12 +50,16 @@
 
 ## Guides
 
+<Card title="Sizing Guide" icon="ruler" href="/enterprise/sizing-guide">
+  Size your node pools, volume storage, and database from peak concurrent sandboxes.
+</Card>
+
 <Card title="Install with Helm" icon="ship" href="/enterprise/k8s-install/installation">
   End-to-end installation instructions using your OpenHands Enterprise license.
 </Card>

 <Card title="Installing Sysbox" icon="cube" href="/enterprise/k8s-install/sysbox">
  Install the Sysbox runtime so agent sandboxes can run securely.
 </Card>

 <Card title="DNS and TLS" icon="lock" href="/enterprise/k8s-install/dns-and-tls">

diff --git a/enterprise/k8s-install/resource-limits.mdx b/enterprise/k8s-install/resource-limits.mdx
@@ -6,7 +6,7 @@

 This guide explains how to configure resource limits for OpenHands Enterprise
 components. Proper resource configuration ensures stable operation and prevents
 issues like OOMKills and pod evictions.

 ## Values File Structure

@@ -25,7 +25,7 @@
 - **Requests**: The minimum resources guaranteed to a pod. The scheduler uses this
  to place pods on nodes with sufficient capacity.
 - **Limits**: The maximum resources a pod can use. Exceeding memory limits causes
  an OOMKill; exceeding CPU limits causes throttling.

 <Warning>
  If a pod uses significantly more memory than its request (but below its limit),
@@ -88,7 +88,7 @@
 | Evictions during node pressure | Pod events show eviction | Increase `requests.memory` to match actual usage |
 | Slow response times | Application latency metrics | Add replicas or increase CPU |

 ### Horizontal Pod Autoscaling

 For automatic scaling based on load, enable the HorizontalPodAutoscaler:

@@ -114,7 +114,7 @@

 ## Sandbox Resources

 Sandboxes (also called runtimes) are the isolated containers where agents execute code.
 Each conversation runs in its own sandbox pod. Configure these via environment variables
 in the `runtime-api.env` section.

@@ -167,9 +167,9 @@

 ### Resource Format

 - **Memory**: Use `Mi` suffix (mebibytes). Examples: `1024Mi`, `4096Mi`, `8192Mi`
 - **CPU**: Use millicores. `1000m` = 1 CPU core. Examples: `500m`, `2000m`, `4000m`
 - **Storage**: Use `Gi` suffix (gibibytes). Examples: `10Gi`, `50Gi`, `100Gi`

 <Warning>
  Changes to sandbox resources only affect **new sandboxes**. Existing running
@@ -258,9 +258,9 @@
 ### Resource usage over time

 For production deployments, we recommend integrating with a monitoring solution
 (Prometheus/Grafana, Datadog, etc.) to track:

 - Memory usage vs. limits (to predict OOMKills)
 - Memory usage vs. requests (to predict evictions)
 - CPU throttling events
 - Pod restart counts
@@ -268,6 +268,9 @@
 ## Next Steps
 
 <CardGroup cols={2}>
+  <Card title="Sizing Guide" icon="ruler" href="/enterprise/sizing-guide">
+    Translate peak concurrent sandboxes into node pools, storage, and database size.
+  </Card>
   <Card title="K8s Install Overview" icon="dharmachakra" href="/enterprise/k8s-install/index">
     Return to the Kubernetes installation overview.
   </Card>

diff --git a/enterprise/quick-start.mdx b/enterprise/quick-start.mdx
@@ -35,6 +35,10 @@
 
 You will need a VM to host OpenHands Enterprise. Choose one of the options below to provision your infrastructure.
 
+<Note>
+  The requirements below are the trial baseline, which comfortably supports about 15 concurrent sandboxes. For a larger rollout, pick your VM from the [Sizing Guide](/enterprise/sizing-guide) before provisioning.
+</Note>
+
 <Tabs>
   <Tab title="AWS with Terraform (Recommended)">
     We provide a [Terraform module](https://github.com/All-Hands-AI/OpenHands-Cloud/tree/main/terraform/aws) that provisions a properly configured environment
@@ -205,7 +209,7 @@
 done
 ```

 Expected: each hostname resolves to your VM's public IP address through the
 wildcard record.

 ### Outbound connectivity checks
@@ -235,7 +239,7 @@
 done
 ```

 Any HTTP response code other than `000` is acceptable for reachability checks
 (for example `200`, `301`, `302`, `401`, `403`, `405`).

 If any check fails, stop and resolve before continuing:
@@ -246,10 +250,10 @@

 | Requirement | Why It Exists |
 |------------|----------------|
 | `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 |
 | `*.<domain>` DNS + cert SAN | Application services and sandboxes are addressed by hostnames under the base domain |
 | `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 |
@@ -300,7 +304,7 @@

  For trials and production deployments, use a publicly trusted TLS certificate whenever possible.
  Private CA certificates may work for users after manual trust setup, but external integrations
  such as GitHub, GitLab, Slack, Jira, and Bitbucket must also trust the certificate chain. If they
  do not, webhook or OAuth callbacks can fail TLS verification and repeatedly retry.
 </Warning>

@@ -320,7 +324,7 @@
 ### 5. Upload TLS certificate (if not provided with the install command)

 If you did not provide certificates with the `install` command, select **"Upload your own"**,
 enter `admin.<your-base-domain>` under **Hostname**, upload your private key and SSL certificate, then click **Continue**.

 If you upload a private CA certificate, make sure any external webhook or OAuth provider that
 calls OpenHands also trusts that CA.
@@ -348,7 +352,7 @@

 ### Domain Configuration

 - Keep the Hostname Configuration Mode set to **"Simple (default)"**
 - Enter your base domain (e.g., `openhands.example.com`)

 ### Certificate Configuration
@@ -389,7 +393,7 @@

 ### Additional Integrations

 If your team uses Jira Data Center or Bitbucket Data Center, follow these guides
 to configure Admin Console values before deployment and complete webhook setup
 inside OpenHands after deployment.

@@ -398,7 +402,7 @@
    Configure Bitbucket Data Center login, repository access, bot identity, and pull request webhooks.
  </Card>
  <Card title="Jira Data Center" icon="building" href="/enterprise/integrations/jira-data-center">
    Configure Jira issue triggers, OAuth account linking, service account credentials, and Jira webhooks.
  </Card>
 </CardGroup>


diff --git a/enterprise/sizing-guide.mdx b/enterprise/sizing-guide.mdx
@@ -0,0 +1,103 @@
+---
+title: Sizing Guide
+description: Recommended VM or Cluster sizing for an OpenHands Enterprise deployment
+icon: ruler
+---
+
+OpenHands Enterprise deployments are sized primarily based on expected **peak concurrent sandboxes** — the largest number of sandboxes you expect to be running at the same time. Keep in mind that one user can have multiple sandboxes running at one time.
+
+<Note>
+  The **Users** column in the tables below is a rough translation of peak sandboxes into headcount, not an input. Size on peak sandboxes; the user estimate is a very rough guide
+</Note>
+
+## Planning Unit
+
+Both tables below are built from the same per-sandbox allocation:
+
+| Resource | Per sandbox |
+|----------|-------------|
+| CPU | 0.5 vCPU |
+| Memory | 4 GiB |
+| Node disk | 10 GiB |
+| Volume storage | 10 GiB |
+
+If you raise the sandbox defaults (for large monorepos or memory-hungry builds), scale the totals in the tables by the same factor. See [Resource Limits](/enterprise/k8s-install/resource-limits) for how to change these values.
+
+## Installation Modes
+
+This guide covers the two supported installation modes:
+
+<CardGroup cols={2}>
+  <Card title="Embedded Cluster (Single VM)" icon="server" href="/enterprise/quick-start">
+    The installer builds a single-node k0s cluster on a VM you provide. Fixed capacity, configured through the Admin Console, everything bundled on one machine.
+  </Card>
+  <Card title="Helm (Existing Kubernetes)" icon="dharmachakra" href="/enterprise/k8s-install/index">
+    Install into a cluster you already run, with standard Kubernetes elasticity and autoscaling.
+  </Card>
+</CardGroup>
+
+## Replicated Embedded Cluster — Single VM
+
+Machine sizes below are based on the peak sandboxes, so feel free to size up or down based on expected usage.
+
+| Peak sandboxes | Users (estimate) | VM | Example machine types | Data disk (starting recommendation) |
+|----------------|------------------|----|-----------------------|-------------------------------------|
+| **5** | ~25 | 8 vCPU / 32 GiB | `e2-standard-8`, `m6i.2xlarge`, `D8s_v5` | 500 GiB SSD |
+| **15** | ~60 | 16 vCPU / 64 GiB | `n2-standard-16`, `m6i.4xlarge`, `D16s_v5` | 1 TiB SSD |
+| **30** | ~125 | 32 vCPU / 128 GiB | `n2-standard-32`, `m6i.8xlarge`, `D32s_v5` | 1.5 TiB SSD |
+| **50** | ~250 | 64 vCPU / 256 GiB | `n2-standard-64`, `m6i.16xlarge`, `D64s_v5` | 3 TiB SSD |
+| **100** | ~400 | 96 vCPU / 384 GiB | `n2-standard-96`, `m6i.24xlarge`, `D96s_v5` | 4 TiB SSD |
+| **Above 100** | — | Use a Kubernetes install, or contact us for a sizing consultation | — | — |
+
+The 16 vCPU / 64 GiB row matches the minimum VM in the [Quick Start](/enterprise/quick-start) system requirements. Trials that stay below roughly 15 concurrent sandboxes are well served by that baseline.
+
+<Warning>
+  **Put the data disk on a separate expandable volume, not the boot disk.** Sandbox volumes on a single VM are host directories that consume actual bytes rather than preallocating, so the disk grows with real usage and is meant to be resized in place as demand increases.
+</Warning>
+
+## Replicated Helm Installation
+
+Use two node pools: a tainted pool that runs **only** sandboxes, and an untainted pool that runs everything else. This keeps a burst of sandboxes from evicting platform components.
+
+Recommended node pools:
+
+- **Sandbox pool**: 16 vCPU / 64 GiB / 400 GiB SSD
+- **Platform pool**: 8 vCPU / 32 GiB / 100 GiB
+
+| Peak sandboxes | Users (estimate) | Sandbox nodes (min–max) | Platform nodes | Volume storage (start) | PostgreSQL (in-cluster by default) |
+|----------------|------------------|-------------------------|----------------|------------------------|------------------------------------|
+| **10** | ~50 | 1–1 | 2 | 1 TiB | 2 vCPU / 8 GiB — fits the platform pool |
+| **25** | ~125 | 1–3 | 2 | 2.5 TiB | 2 vCPU / 8 GiB — fits the platform pool |
+| **50** | ~250 | 1–5 | 2 | 5 TiB | 2 vCPU / 8 GiB — fits the platform pool |
+| **100** | ~500 | 1–10 | 3 | 10 TiB | 4 vCPU / 16 GiB — fits the platform pool |
+| **200** | ~1,000 | 2–20 | 3 | 20 TiB | 4 vCPU / 16 GiB — fits the platform pool |
+| **500** | ~2,500 | 3–48 | 4 | 50 TiB | 8 vCPU / 32 GiB — **needs a dedicated node** |
+| **1,000** | ~5,000 | 5–96 | 5 | 100 TiB | 16 vCPU / 64 GiB — **needs a dedicated node** |
+
+Notes on the table:
+
+- **Minimum node counts assume autoscaling.** If your cluster cannot scale up quickly, raise the minimum toward your typical daily peak so users don't wait on node provisioning.
+- **PostgreSQL** is deployed in-cluster by default. At 500 peak sandboxes and above, give it a dedicated node — or use [External PostgreSQL](/enterprise/external-postgres) and size it with your database team.
+
+## Adjusting After Rollout
+
+- Track sandbox pod count over time and size to the observed peak, plus headroom.
+- Watch memory usage against limits to catch OOMKills, and usage against requests to catch evictions. See [Resource Limits](/enterprise/k8s-install/resource-limits) for the metrics and the settings to change.
+- Grow volume storage before it fills. Sandbox workspaces are deleted with their sandbox, but their usage and retention may outstrip initial storage numbers
+
+## Next Steps
+
+<CardGroup cols={2}>
+  <Card title="Quick Start" icon="rocket" href="/enterprise/quick-start">
+    Provision a VM and install OpenHands Enterprise.
+  </Card>
+  <Card title="Kubernetes Installation" icon="dharmachakra" href="/enterprise/k8s-install/index">
+    Deploy into an existing cluster with Helm.
+  </Card>
+  <Card title="Resource Limits" icon="gauge-high" href="/enterprise/k8s-install/resource-limits">
+    Tune CPU, memory, and storage for the application server and sandboxes.
+  </Card>
+  <Card title="Conversations and Sandboxes" icon="boxes-stacked" href="/enterprise/conversations-and-sandboxes">
+    Understand how conversations map onto sandboxes and how placement affects capacity.
+  </Card>
+</CardGroup>