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

All configuration examples in this guide show keys that belong in your site-values.yaml file. The examples show the complete path from the root of the file.
Create a site-values.yaml file to store your custom configuration. Pass it to Helm with -f site-values.yaml when installing or upgrading.

​
Understanding Kubernetes Resources

Kubernetes uses two key resource settings:
  • 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.
If a pod uses significantly more memory than its request (but below its limit), it becomes a candidate for eviction during node pressure. Set requests close to actual usage for production workloads.

​
Application Server Resources

The OpenHands application server (deployment name: openhands) handles the UI, API, and agent orchestration. Configure its resources under the deployment section in your values file.

​
Default Configuration

# site-values.yaml

# ============================================================================
# Application Server (OpenHands deployment)
# ============================================================================
# Root-level key: deployment
# Controls the main OpenHands server pod resources
# ============================================================================
deployment:
  replicas: 1
  resources:
    requests:
      memory: 1200Mi
      cpu: 100m
    limits:
      memory: 3Gi
For production workloads, increase memory and add replicas for redundancy: 
# site-values.yaml

deployment:                        # Root-level key
  replicas: 2
  resources:
    requests:
      memory: 2560Mi               # 2.5Gi - aligns with typical usage
      cpu: 100m
    limits:
      memory: 4Gi                  # Buffer against OOMKill

​
When to Adjust

Increase resources if you observe:
SymptomMetric to CheckAction
Pod restartsRESTARTS column in kubectl get podsIncrease limits.memory
High memory usagekubectl top pods shows >80% of limitIncrease limits.memory
Evictions during node pressurePod events show evictionIncrease requests.memory to match actual usage
Slow response timesApplication latency metricsAdd replicas or increase CPU

​
Horizontal Pod Autoscaling

For automatic scaling based on load, enable the HorizontalPodAutoscaler: 
# site-values.yaml

deployment:                        # Root-level key
  replicas: 2                      # Minimum baseline
  resources:
    requests:
      memory: 2560Mi
      cpu: 200m                    # Increase for HPA to use as scaling signal
    limits:
      memory: 4Gi

autoscaling:                       # Root-level key (separate from deployment)
  enabled: true
  minReplicas: 2
  maxReplicas: 5
  targetCPUUtilizationPercentage: 80
  targetMemoryUtilizationPercentage: 80

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

​
Available Settings

VariableDefaultDescription
MEMORY_REQUEST3072MiMinimum memory guaranteed per sandbox
MEMORY_LIMIT3072MiMaximum memory per sandbox
CPU_REQUEST500mMinimum CPU guaranteed (500m = 0.5 cores)
CPU_LIMIT(none)Maximum CPU per sandbox
EPHEMERAL_STORAGE_SIZE10GiTemporary storage per sandbox

​
Default Configuration

# site-values.yaml

# ============================================================================
# Runtime API (Sandbox Manager)
# ============================================================================
# Root-level key: runtime-api
# This is a subchart that manages sandbox pod lifecycle.
# The env section passes environment variables to the runtime-api container,
# which uses them when creating sandbox pods.
# ============================================================================
runtime-api:
  env:
    MEMORY_REQUEST: "3072Mi"
    MEMORY_LIMIT: "3072Mi"
    CPU_REQUEST: "500m"
    EPHEMERAL_STORAGE_SIZE: "10Gi"

​
High-Resource Configuration

For workloads that require more resources (large codebases, memory-intensive builds): 
# site-values.yaml

runtime-api:                       # Root-level key (subchart configuration)
  env:
    MEMORY_REQUEST: "8192Mi"
    MEMORY_LIMIT: "8192Mi"
    CPU_REQUEST: "2000m"
    CPU_LIMIT: "4000m"
    EPHEMERAL_STORAGE_SIZE: "50Gi"

​
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
Changes to sandbox resources only affect new sandboxes. Existing running sandboxes keep their original limits until stopped and restarted.

​
Applying Changes

​
1. Update your values file

Edit site-values.yaml with your desired configuration: 
# site-values.yaml
#
# This file contains your custom overrides for the OpenHands Helm chart.
# All keys shown here are root-level keys in the values hierarchy.

# ============================================================================
# Application Server Resources
# ============================================================================
deployment:
  replicas: 2
  resources:
    requests:
      memory: 2560Mi
      cpu: 100m
    limits:
      memory: 4Gi

# ============================================================================
# Sandbox Resources (via Runtime API subchart)
# ============================================================================
runtime-api:
  env:
    MEMORY_REQUEST: "8192Mi"
    MEMORY_LIMIT: "8192Mi"
    CPU_REQUEST: "2000m"
    CPU_LIMIT: "4000m"
    EPHEMERAL_STORAGE_SIZE: "50Gi"

​
2. Apply with Helm upgrade

helm upgrade openhands \
  oci://ghcr.io/all-hands-ai/helm-charts/openhands \
  -f site-values.yaml \
  -n openhands

​
Verifying Changes

​
Check application server resources

kubectl get deployment openhands -n openhands \
  -o jsonpath='{.spec.template.spec.containers[0].resources}' | jq

​
Check replica count

kubectl get deployment openhands -n openhands \
  -o jsonpath='{.spec.replicas}'

​
Check runtime-api environment variables

Verify the sandbox resource settings are configured in the runtime-api deployment: 
kubectl get deployment runtime-api -n openhands \
  -o jsonpath='{.spec.template.spec.containers[0].env}' | \
  jq '.[] | select(.name | test("MEMORY|CPU|STORAGE"))'

​
Monitoring Resource Usage

​
Current resource consumption

kubectl top pods -n openhands

​
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

​
Next Steps

K8s Install Overview

Return to the Kubernetes installation overview.

Enterprise Overview

Learn more about OpenHands Enterprise features.