Skip to content

docs: Multiple custom sandbox images with warm runtime pools - #609

Open
jpshackelford wants to merge 7 commits into
mainfrom
docs/warm-runtime-custom-images
Open

docs: Multiple custom sandbox images with warm runtime pools#609
jpshackelford wants to merge 7 commits into
mainfrom
docs/warm-runtime-custom-images

Conversation

@jpshackelford

@jpshackelford jpshackelford commented Jul 8, 2026

Copy link
Copy Markdown
Member

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

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.

@openhands-agent
docs: replace custom sandbox image guide with warm runtime pools appr…
bbc0fd4 
…oach

- Replaces single-image legacy approach with multi-image warm runtime pool documentation
- Key benefits: no restarts/redeployments, dynamic updates, multiple images
- Complete guide to authentication, configuration, and usage
- Includes working shell scripts for managing warm runtime configs
- Documents three methods for starting conversations (API, SDK, Web UI)
- Adds image lifecycle management strategies for handling updates and resume
- Covers troubleshooting for common issues (auth, image pulls, resume failures)

Co-authored-by: openhands <openhands@all-hands.dev>
@mintlify

mintlify Bot commented Jul 8, 2026 •
edited
Loading

Copy link
Copy Markdown

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

Project Status Preview Updated
all-hands-ai 🟢 Ready View Preview Sep 15, 2026, 2:35 PM

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

@ak684 ak684 mentioned this pull request Aug 31, 2026
Merged
@ak684 ak684 mentioned this pull request Sep 2, 2026
Merged
@openhands-agent
Fix custom sandbox image docs: Replicated vs Helm accuracy
0554b39 
Correct four inaccuracies found by cross-referencing the runtime-api and
OpenHands-Cloud codebases:

**Admin password (Step 1):**
- Replicated: password is auto-generated at install (RandomString 32), already
  in the secret. The script reads it automatically. No kubectl-patch step is
  needed or appropriate — the Admin Console manages the secret and overwrites
  kubectl-patches on every deploy.
- Helm: password was created manually during installation (kubectl create secret
  generic admin-password). No setup step required; added rotation instructions.
- Both tabs now give the correct "how to change" path for each install type.

**Overlay vs. legacy mode (How It Works):**
- Replicated always sets WARM_RUNTIME_CONFIG_OVERLAY=1 via openhands.yaml. API
  configs layer on top of the ConfigMap rather than replacing it; the installer's
  v1_current pool stays live. The "first save takes over" warning was wrong.
- Helm uses legacy mode by default (env var not set in chart values). The takeover
  warning is correct there. Added opt-in instructions for overlay mode.
- Converted to Tabs so each install type gets accurate framing.

**Step 3 (re-declare v1_current):**
- Added inline Note: on Replicated the installer's v1_current pool was never
  replaced, so re-saving it is optional (only needed to change the image). On Helm
  it remains required.

**Reverting section:**
- Added Note clarifying that on Replicated, deleting all API configs lifts
  overrides but the ConfigMap entries (never replaced) continue as sole source.
  On Helm, deleting all API configs restores ConfigMap management.

**Troubleshooting:**
- Fixed wrong claim that the password is reset after every Admin Console deploy.
  It only changes if updated via the Admin Console.
- Fixed cache time: app server 60 s + UI up to 5 min; advise navigating away and
  back to force a fresh fetch.

**API Reference:**
- Added missing fuse_s3_mount and source fields to the GET response description.
- Corrected "only DB configs listed" to distinguish overlay mode (full effective
  set, Replicated) from legacy mode (DB only, Helm default).

**Configuration Format table:**
- Added fuse_s3_mount field with description of its FUSE/PVC semantics.

Co-authored-by: openhands <openhands@all-hands.dev>
@openhands-agent
chore: add QA test results for warm runtime pool feature
77b75c2 
Results from end-to-end testing of PR #609 on replicated-test-03.
Tests cover: basic lifecycle, overlay semantics, real image pull.
.pr/ directory is temporary and will be removed before merge.

Co-authored-by: openhands <openhands@all-hands.dev>
@jpshackelford jpshackelford mentioned this pull request Sep 15, 2026
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@jpshackelford @openhands-agent @ak684