docs: Multiple custom sandbox images with warm runtime pools

[jpshackelford]

Summary

Replaces the legacy single-image custom sandbox documentation with comprehensive guide for the new warm runtime pool approach (PR #538 in runtime-api).

Key Changes

What's New

• Multiple custom images: Configure different images for different project types
• Dynamic updates: Add/update/remove images via API without restarting OpenHands
• No redeployments: Changes take effect in ~1 minute (next reconciler cycle)
• Instant startup: Warm pools eliminate 20+ second cold starts

Documentation Sections

1. Introduction & Benefits

   • Explains warm runtime pools concept
   • Highlights operational advantages over legacy approach
   • Multiple image use cases (PHP, Java, mobile, data science, etc.)

2. Prerequisites

   • Image building guidelines (extends existing SDK docs)
   • Admin password setup (kubectl-based, one-time)
   • Private registry configuration

3. Managing Warm Runtime Configurations

   • Complete authentication flow (challenge-response PBKDF2)
   • Working shell script: manage-warm-runtimes.sh
   • Configuration format reference table
   • Add/update/delete operations

4. Starting Conversations

   • Method 1: Direct Runtime API calls (curl examples)
   • Method 2: OpenHands SDK (Python examples)
   • Method 3: Web UI (3 options: global default, custom logic, direct API)

5. Verifying and Monitoring

   • Check warm pool status
   • Monitor pod creation
   • Verify image pulls
   • Troubleshoot warm runtime claiming

6. Image Lifecycle Management ⭐ NEW

   • How resume works (S3-backed vs PVC-backed)
   • Image update strategies (keep old tags, force fresh, gradual rollout)
   • Best practices for versioning
   • What happens when images go missing
   • Resume failure troubleshooting

7. API Reference

   • GET /api/warm-runtime-configs
   • PUT /api/admin/warm-runtime-configs/{name}
   • DELETE /api/admin/warm-runtime-configs/{name}

8. Migration Guide

   • Moving from Replicated Admin Console single-image approach

Related Work

• Runtime-API PR docs: sync llms context files #538: Warm runtime config REST API endpoints (merged June 16, 2026)
• Issue docs: register_agent is in subagent, not in delegate #468: Original problem statement for custom image support
• Consultation with @tofarr confirmed proposed issues docs: sync llms context files #596, #14824, #14825 are NOT needed—functionality exists in PR docs: sync llms context files #538

Technical Details

Authentication: Documents admin password setup via kubectl (password not auto-generated in Replicated VM installs)

Script included: Full working manage-warm-runtimes.sh (no placeholders)—runs inside runtime-api pod via kubectl exec

Image lifecycle: Critical guidance on:

• S3-backed runtimes resume with original image tag (must keep old tags available)
• PVC-backed runtimes can auto-update to "current" image on resume
• Registry cleanup strategies to balance storage vs resume capability
• Resume failure scenarios when images are deleted

Testing

• Verified all kubectl commands
• Validated authentication flow against runtime-api code
• Checked API endpoints match management_fastapi.py
• Confirmed resume behavior from runtimes.py analysis

Migration Impact

The new approach coexists with the legacy Replicated Admin Console single-image setting. Users can:

1. Keep using legacy approach (no breaking changes)
2. Migrate gradually (both approaches work simultaneously)
3. Adopt warm pools for multi-image support

---

This PR was created by an AI assistant (OpenHands) on behalf of @jpshackelford.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
all-hands-ai	🟢 Ready	View Preview	Jul 8, 2026, 7:33 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.