[Enterprise] Support multiple custom sandbox images from runtime-api warm pool

Problem Statement

Enterprise customers on self-hosted deployments need to use custom runtime container images with project-specific toolchains (e.g., PHP 8.4 for a Symfony project, Java 21 for a Spring Boot project, custom build environments).

Currently, OpenHands only supports a single pre-configured runtime image. Customers cannot:

• Use multiple different runtime images for different projects
• Specify custom container images when starting conversations
• Use images from private registries without complex workarounds
• Pre-warm custom images to avoid cold start latency

This blocks enterprise teams from using OpenHands effectively across polyglot codebases.

Customer Context

C24 (HappyFox Ticket #OS00000055):

• VM-based Replicated deployment
• Needs project-specific images from private Harbor registry (harbor.c24.de/)
• Requires PHP extensions, MySQL, Redis, WireMock, PHPUnit, iOS/Android toolchains
• Currently blocked from scaling OpenHands across multiple teams

Related Linear Issue: APP-2354

Proposed Solution

Enable multiple custom sandbox images with pre-warming support:

1. Runtime-API manages warm pools - Admins configure custom image pools via API
2. Per-image warm counts - Each custom image can have its own pool size
3. Conversation API selects image - Users specify which image to use when starting conversations
4. Private registry support - Pull images from private registries using K8s secrets

Implementation Plan

This work is broken into child issues:

Runtime-API (OpenHands/runtime-api)

• OpenHands/runtime-api#595 - Add warm runtime configuration management API (PR OpenHands/OpenHands#538)
• OpenHands/runtime-api#596 - Add warm runtime status endpoint

OpenHands Backend & API (OpenHands/OpenHands)

• OpenHands/enterprise#33 - Support custom sandbox images in conversation start API

End-to-End Flow

Admin setup:

# 1. Configure warm runtime via API
curl -X PUT https://runtime-api/api/admin/warm-runtime-configs/c24-pemservice \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -d '{
    "image": "harbor.c24.de/c24/pemservice:latest",
    "count": 3,
    "working_dir": "/workspace",
    "command": ["/usr/local/bin/openhands-agent-server", "--port", "60000"],
    "environment": {...}
  }'

# 2. Verify warm runtimes are ready
curl https://runtime-api/api/admin/warm-runtime-configs/status

User starts conversation with custom image:

POST /api/v1/app-conversations
{
  "sandbox_spec_id": "harbor.c24.de/c24/pemservice:latest",
  "github_repo": "https://github.com/company/php-project",
  ...
}

Technical Design

Full design documentation: OpenHands/technical-explorations - C24 Custom Sandbox Images

Out of Scope (Follow-on Work)

• UI dropdown for image selection (can use API directly for now)
• Replicated admin console UI for warm runtime management
• Auto-discovery of available images in UI

---

Related:

• Linear: APP-2354
• HappyFox: #OS00000055
• runtime-api PR: #538

Start with the linked technical exploration, then review runtime-api issues #595 and #596 and enterprise issue #33 to understand the warm-pool and conversation API boundaries. Trace the app-conversations request and the runtime-api warm-runtime configuration and status endpoints. Done means custom images can be configured with per-image warm counts, selected when starting conversations, and pulled from private registries using Kubernetes secrets.