Publish warm-sandbox-pool to the docs Cookbook tab

[jpshackelford]

Why

#3 added warm-sandbox-pool before the style guide existed, with no example.yaml, so it is not on docs.openhands.dev and is missing from the root README table. This brings it through the upleveling checklist as a restructure only. Apart from the review fix below, no prose is removed or reworded, and nothing is added to the behavior or options.

• example.yaml (new): category Sandbox lifecycle, icon fire (unused in that category), and a one-sentence description taken from the README's own intro. The root README table gets a matching row.

• Sections in the standard order: Concept becomes How It Works with the architecture diagram under it, Quick Start is split into Prerequisites and Run It, and Related Examples becomes Related. The demo-application section and the other topic sections follow Run It, and License stays last.

• Polish: the ASCII box diagram becomes a mermaid flowchart with the same parties and labels. The two blockquote asides ("Heads up: this creates real sandboxes", "Security: what the access code does and does not protect") become [!WARNING] alerts. Running locally and running from an OpenHands sandbox are now tabs. The "Context: Alternative to Custom Images" background is a collapsed <details> block. The sample prompt and the file tree get the text language. Related items are cards with relative links.

• Review fix: the README framed the technique as being about deploying Ruby apps. Per review, the intro now says it applies to any situation where expensive setup must finish before an agent can start, and that it can be combined with custom images. The Context section says OpenHands Enterprise has robust support for custom sandbox images while custom images are not yet supported on SaaS, and lists why an image may still not be enough (setup that changes faster than an image can be rebuilt, setup that varies by task). The three other places that said "SaaS/Cloud" now say "SaaS", so it is clear which product lacks custom images; "OpenHands Cloud API" and "API key" wording is unchanged. The demo paragraph says the Ruby service is only an example, and "Large Codebases" names a very large monorepo and a Java monorepo with heavy Maven dependencies. Those examples come from the review comment.

Left out on purpose, because each needs new content and should be reviewed on its own:

• An APIs Used table. The README names the endpoints in prose but has no table.
• A rewritten How It Works. It reuses the existing "Concept" text.
• QUICKSTART.md, which stays as is.
• The flask dependency, which the style guide's "standard library plus requests" rule does not cover.

Validation

• No content lost — compared the old and new README line by line in both directions. The only original lines absent from the new file are the replaced headings (Context…, Concept, Architecture, Quick Start, ### Prerequisites, Related Examples), the ASCII box drawing, and three bare ``` fence markers. The only new lines are structure (<details>, tab and card markers, alert markers, new headings, `text` labels), the mermaid block, and the three Related card links. Word-for-word, no prose word is missing or added outside the diagram. The file goes from 455 to 451 lines. The review fixes change the intro sentence, the Context section, the demo paragraph, one line under "Large Codebases", and three lines that said "SaaS/Cloud".
• Diagram — mermaid parsed the flowchart as valid (flowchart-v2). It keeps the Web UI with its two panes and three sandbox states, the Pool Controller (Flask backend), three READY sandboxes, and "Each sandbox has Ruby + Sinatra gem + demo service".
• Rendering — npm run check in tools/docs-render renders 25 examples, including this one. The rendered page has the accordion, two tabs, two warnings, the mermaid block and the card group. The converter check passing does not itself show the page looks right, so please check the docs preview comment on this PR.
• Pre-commit — yamlfmt, whitespace and YAML checks pass on the changed files. No Python files changed.

This PR was drafted by an AI agent on behalf of the user.

@jpshackelford can click here to continue refining the PR

[github-actions]

Coverage Report

File	Stmts	Miss	Cover	Missing
__init__.py	5	0	100%
cli.py	65	3	95%	59–60, 100
client.py	105	17	84%	56, 109, 117, 150, 160–162, 173, 203, 206–208, 210, 217–219, 221
metrics.py	80	2	98%	102, 182
v0.py	48	3	94%	88, 104, 141
v1.py	83	9	89%	86, 90, 94, 131, 135, 155, 178, 206, 214
TOTAL	386	34	91%

[github-actions]

Docs preview

✅ Docs preview is ready: https://allhandsai-cookbook-preview-pr-21.mintlify.site

Page	Change
/cookbook	updated
/cookbook/warm-sandbox-pool	added

Docs PR: OpenHands/docs#912 (draft preview; never merged, closes with this PR).
Rendered from 28d5c99. After merge, a separate sync PR updates the docs.

[github-actions]

Clean documentation restructuring that successfully brings warm-sandbox-pool up to the style guide standards for publishing on docs.openhands.dev.

What's working well:

• ✅ All required upleveling checklist items completed
• ✅ Rendering validation passes (25 examples render cleanly)
• ✅ Structure follows standard order with proper Title Case headings
• ✅ ASCII diagram → mermaid conversion preserves all content
• ✅ Tabs, alerts, details blocks, and cards properly implemented
• ✅ example.yaml complete with unique icon in "Sandbox lifecycle" category
• ✅ Root README table updated
• ✅ No old repository references

One suggestion for follow-up:

🟡 Consider adding an "APIs Used" section in a follow-up PR. The style guide recommends this section "when it calls the API" (which this example does), and other published examples include it. However, I understand this PR is intentionally limited to restructuring without adding new prose content, so deferring this is reasonable.

[RISK ASSESSMENT]

• Risk level: LOW (documentation-only changes)
• Scope: Restructures one example README to match style guide
• Testing: Rendering validation passed, all 25 examples render cleanly
• Impact: Enables publishing to docs site; no behavior changes

---

Was this automated review useful? React with 👍 or 👎 to this review to help us measure review quality.
Workflow run: https://github.com/OpenHands/enterprise-cookbook/actions/runs/37774891036

[jpshackelford]

The doc says deploying Ruby-based applications. This is incorrect. This is about any situation where expensive setup is required before an agent can start working and where a custom image does not address the issue adequately. A custom image may not be possible--for example they aren't supported on SaaS--or may not fully address the situation in cases where the setup required changes significantly over a shorter period then is practical for rebuilding the image or if a significant part of the setup is highly variable on the task and it would be impractical to have a custom image for each variation.

This technique can also be combined with the use of custom images.

I also see "The Sinatra service demonstrates how Ruby-based systems". Once again, the Ruby application is just an example. Any long startup job would apply here.

Another such case is of long startup is cloning of a very large mono repo or downloading heavy maven dependencies for a java mono repo with 50+ projects.