@openhands/extensions 0.25.0 → 0.26.0

package/automations/catalog/github-agents-md-maintainer/manifest.json

@@ -84,7 +84,7 @@
       }
     },
     "bundle": {
-      "version": "1.0.0",
+      "version": "1.1.0",
       "entrypoint": "python3 main.py",
       "timeout": 900,
       "files": {

package/automations/catalog/github-pr-reviewer/manifest.json

@@ -1,9 +1,9 @@
 {
   "id": "github-pr-reviewer",
-  "version": "1.8.0",
+  "version": "1.8.1",
   "name": "GitHub code review",
   "category": "Code review",
-  "description": "Review requested pull-request heads, resume an outstanding reviewer request on a schedule once its checks are green, review a bounded rotating window of open non-draft pull requests that nobody requested once their current head is green and unreviewed, drain the backlog oldest-first under a small per-scan new-conversation bound, record exact-head decisions, stop early on out-of-scope changes, and optionally request a code-aware human maintainer after approval or a maintainer-decision scope stop.",
+  "description": "Review requested pull-request heads, resume an outstanding reviewer request on a schedule once its checks are green, classify all open non-draft pull requests that nobody requested and review eligible green heads, drain the backlog oldest-first under a small per-scan new-conversation bound, record exact-head decisions, stop early on out-of-scope changes, and optionally request a code-aware human maintainer after approval or a maintainer-decision scope stop.",
   "requires": {
     "integrations": {},
     "features": [
@@ -13,7 +13,7 @@
   },
   "popularityRank": 100,
   "estimatedSetupMinutes": 4,
-  "exampleImplementation": "A scheduled scan of the trigger label, of open non-draft PRs holding an outstanding reviewer request, and of a bounded rotating window of open non-draft PRs nobody requested whose current head is green and unreviewed, or a GitHub reviewer-request event, selects a PR head and submits an idempotent subject turn. The unrequested window resumes from a per-repository position kept in the Automation KV store, so each scan reads a bounded number of pull requests while still covering the backlog over time, and explicit requests are always examined. The scheduled scan orders eligible heads with explicit requests first and then oldest-first, and starts at most a small configurable number of new conversations per scan across every repository. The profile-backed agent clones that exact head in its runtime, applies an early repository-ownership and product/architecture scope gate, then reuses the established review workflow, runs appropriate tests, and publishes a readable native review. A native approval, or a maintainer-decision scope stop, can then be handed to a code-aware human maintainer.",
+  "exampleImplementation": "A scheduled scan of the trigger label, of open PRs (including drafts) holding an outstanding reviewer request, and of every open non-draft PR nobody requested whose current head may be green and unreviewed, or a GitHub reviewer-request event, selects a PR head and submits an idempotent subject turn. Each scheduled scan classifies the full backlog, while the global per-run quota limits only newly created review conversations; blocked and pending heads consume no launch slot, and explicit requests retain priority. The scheduled scan orders eligible heads with explicit requests first and then oldest-first, and starts at most a small configurable number of new conversations per scan across every repository. The profile-backed agent clones that exact head in its runtime, applies an early repository-ownership and product/architecture scope gate, then reuses the established review workflow, runs appropriate tests, and publishes a readable native review. A native approval, or a maintainer-decision scope stop, can then be handed to a code-aware human maintainer.",
   "impact": {
     "basis": "completed-runs",
     "one": "1 PR review sweep completed",
@@ -68,7 +68,7 @@
         "triggerLabel": {
           "type": "text",
           "label": "Trigger label",
-          "help": "Pull requests carrying this label are reviewed. An open, non-draft pull request that nobody requested is also reviewed once its current head is green and carries no review yet, examined a bounded rotating window at a time so one scan reads only a slice of the backlog.",
+          "help": "Pull requests carrying this label are reviewed. An open, non-draft pull request that nobody requested is also reviewed once its current head is green and carries no review yet, with the whole backlog classified each scan and only newly launched reviews counting against the configured quota.",
           "default": "openhands-review",
           "required": true,
           "constraints": {
@@ -135,7 +135,7 @@
       }
     },
     "bundle": {
-      "version": "1.8.0",
+      "version": "1.8.1",
       "entrypoint": "python3 worker.py",
       "timeout": 300,
       "files": {

package/automations/catalog/github-stale-ci-pr-closer/manifest.json

@@ -1,6 +1,6 @@
 {
   "id": "github-stale-ci-pr-closer",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "name": "GitHub stale CI cleanup",
   "category": "Code review",
   "description": "Warn and close abandoned pull requests whose required CI remains failing.",
@@ -11,7 +11,7 @@
     ]
   },
   "estimatedSetupMinutes": 3,
-  "exampleImplementation": "A deterministic scheduled scan reads the required checks that apply to each pull request's base branch. It warns after seven days of observed failure and closes after seven more days only when the author has neither pushed nor commented.",
+  "exampleImplementation": "A deterministic scheduled scan reads the required checks that apply to each pull request's base branch. It warns seven days after the newest required-check failure and closes seven days later only when the author has neither pushed nor commented.",
   "setup": {
     "version": "1.0",
     "mode": "direct",
@@ -53,7 +53,7 @@
       }
     },
     "bundle": {
-      "version": "1.0.0",
+      "version": "1.0.1",
       "entrypoint": "python3 worker.py",
       "timeout": 300,
       "files": {

package/automations/catalog/gitlab-issue-to-mr/manifest.json

@@ -105,7 +105,7 @@
       }
     },
     "bundle": {
-      "version": "1.0.0",
+      "version": "1.1.0",
       "entrypoint": "python3 main.py",
       "timeout": 900,
       "files": {

package/automations/catalog/news-digest/manifest.json

@@ -12,7 +12,7 @@
   },
   "popularityRank": 78,
   "estimatedSetupMinutes": 2,
-  "exampleImplementation": "Trigger: cron, daily by default (0 8 * * *)\nRequired secret: none. The feeds are public URLs and the conversation is started with an empty secret allow-list and no MCP servers.\n\n1. Read the feed list, the topics, and the schedule from setup.\n2. Key one unit of work to the UTC date, so a cron that fires more often, a retried run, or a restarted service cannot write the same digest twice.\n3. Fetch every feed over plain HTTPS and parse RSS 2.0, RSS 1.0/RDF and Atom by local element name. A feed that is down, moved, or no longer a feed is reported and skipped; the run fails only when every feed fails.\n4. Drop stories already covered by an earlier digest and stories older than the lookback window. Do not judge what a story is about: that has no right answer and is the agent's call.\n5. Start no conversation at all when nothing new was published, and leave the day open for a later run. A quiet day costs no tokens.\n6. Otherwise start an OpenHands conversation with the newest stories and the topics in the prompt, and let it decide which are relevant, group them, merge duplicate coverage, and write the digest.\n7. Deliver it three ways that need no credentials: it stays in the conversation, it is printed into the run log, and its opening is kept in state.\n8. Remember the reported stories only once a digest exists, so a failed run is recovered by the next one rather than lost.",
+  "exampleImplementation": "Trigger: cron, daily by default (0 8 * * *)\nRequired secret: none. The feeds are public URLs and, on a local Agent Canvas, the conversation is started with an empty secret allow-list and no MCP servers. On OpenHands Cloud and Enterprise it is started with the user's own settings.\n\n1. Read the feed list, the topics, and the schedule from setup.\n2. Key one unit of work to the UTC date, so a cron that fires more often, a retried run, or a restarted service cannot write the same digest twice.\n3. Fetch every feed over plain HTTPS and parse RSS 2.0, RSS 1.0/RDF and Atom by local element name. A feed that is down, moved, or no longer a feed is reported and skipped; the run fails only when every feed fails.\n4. Drop stories already covered by an earlier digest and stories older than the lookback window. Do not judge what a story is about: that has no right answer and is the agent's call.\n5. Start no conversation at all when nothing new was published, and leave the day open for a later run. A quiet day costs no tokens.\n6. Otherwise start an OpenHands conversation with the newest stories and the topics in the prompt, and let it decide which are relevant, group them, merge duplicate coverage, and write the digest.\n7. Deliver it three ways that need no credentials: it stays in the conversation, it is printed into the run log, and its opening is kept in state.\n8. Remember the reported stories only once a digest exists, so a failed run is recovered by the next one rather than lost.",
   "impact": {
     "basis": "completed-runs",
     "one": "1 feed check completed",
@@ -65,7 +65,7 @@
       }
     },
     "bundle": {
-      "version": "1.0.0",
+      "version": "1.1.0",
       "entrypoint": "python3 main.py",
       "timeout": 900,
       "files": {

package/index.d.ts

@@ -44,3 +44,5 @@ export type {
 } from "./automations/index.js";
 export { SKILLS_CATALOG, DEFAULT_ENABLED_SKILL_NAMES } from "./skills/index.js";
 export type { SkillCatalogEntry } from "./skills/index.js";
+export { APPS_CATALOG } from "./apps/index.js";
+export type { AppCatalogEntry } from "./apps/index.js";

package/index.js

@@ -1,3 +1,4 @@
 export { INTEGRATION_CATALOG } from "./integrations/index.js";
 export { AUTOMATION_CATALOG, AUTOMATION_INTERFACE } from "./automations/index.js";
 export { SKILLS_CATALOG, DEFAULT_ENABLED_SKILL_NAMES } from "./skills/index.js";
+export { APPS_CATALOG } from "./apps/index.js";

package/marketplaces/openhands-extensions.json

@@ -541,6 +541,20 @@
         "semver"
       ]
     },
+    {
+      "name": "runtime-api-configs",
+      "source": "./plugins/runtime-api-configs",
+      "description": "Manage warm sandbox pools on OpenHands Enterprise from a Python CLI: list, template, save, and delete warm runtime configurations against the runtime-api, and bootstrap credentials from Kubernetes secrets. Standard-library only, runs anywhere python3 is available.",
+      "category": "environment",
+      "keywords": [
+        "openhands-enterprise",
+        "runtime-api",
+        "warm-runtime-config",
+        "warm-pool",
+        "custom-sandbox-image",
+        "admin"
+      ]
+    },
     {
       "name": "security",
       "source": "./skills/security",
@@ -896,6 +910,16 @@
       "source": "./skills/github-stale-ci-pr-closer",
       "description": "Warn and close abandoned pull requests whose required CI remains failing.",
       "category": "automations"
+    },
+    {
+      "name": "use-jev",
+      "source": "./skills/use-jev",
+      "description": "Use Jev, a general classifier, for typed choices, scores, and yes/no probabilities in software.",
+      "category": "integrations",
+      "keywords": [
+        "jev",
+        "classification"
+      ]
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openhands/extensions",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "Public OpenHands extension catalogs for skills, plugins, integrations, and automation templates.",
   "license": "MIT",
   "type": "module",
@@ -12,6 +12,8 @@
     "build:skills": "node scripts/build-skills-catalog.mjs",
     "build:integrations": "node scripts/build-integration-catalog.mjs",
     "build:automations": "node scripts/build-automation-catalog.mjs",
+    "build:vscode-app": "node apps/vscode/scripts/package.mjs",
+    "test:vscode-app": "node tests/vscode-app.test.mjs",
     "build": "npm run build:skills && npm run build:integrations && npm run build:automations"
   },
   "engines": {
@@ -51,6 +53,12 @@
       "import": "./skills/index.js",
       "default": "./skills/index.js"
     },
+    "./apps": {
+      "types": "./apps/index.d.ts",
+      "import": "./apps/index.js",
+      "default": "./apps/index.js"
+    },
+    "./apps/*": "./apps/*",
     "./skills/*": "./skills/*",
     "./plugins/*": "./plugins/*",
     "./marketplaces/*.json": "./marketplaces/*.json",

package/plugins/openhands/skills/openhands-api/README.md

@@ -22,7 +22,7 @@ The Python client prefers `OPENHANDS_CLOUD_API_KEY` and falls back to `OPENHANDS
 
 ## Delegating work with new Cloud conversations
 
-Use `POST /api/v1/app-conversations` to create a separate OpenHands Cloud conversation for a self-contained task, then poll `GET /api/v1/app-conversations/start-tasks?ids=...` until you have an `app_conversation_id`.
+Use `POST /api/v1/app-conversations` to create a separate OpenHands Cloud conversation for a self-contained task, then poll `GET /api/v1/app-conversations/start-tasks?ids=...` until you have an `app_conversation_id`. Share the Agent Canvas link from `OpenHandsAPI.app_conversation_ui_url(app_conversation_id)` (the conversation's `conversation_ui_url`, falling back to `<base_url>/canvas/conversations/<id>`).
 
 Keep delegated prompts self-contained: include the repository, branch, relevant files, constraints, and expected output. Prefer five or fewer concurrently running delegated conversations.
 

package/plugins/openhands/skills/openhands-api/SKILL.md

@@ -177,7 +177,7 @@ When you start a delegated Cloud conversation:
 3. Start the new conversation with `POST /api/v1/app-conversations`.
 4. Poll the start-task until `status` is `READY` and you have an `app_conversation_id`.
 5. Monitor the delegated conversation via `GET /api/v1/app-conversations?ids=...`.
-6. Share or store the Cloud URL: `https://app.all-hands.dev/conversations/<app_conversation_id>`.
+6. Share or store the conversation's `conversation_ui_url` from that response. It opens the conversation in Agent Canvas. If the server does not return it, use `<base_url>/canvas/conversations/<app_conversation_id>`, where `<base_url>` is the server you called the API on. Never share `conversation_url`; it is the sandbox's agent-server API, not a page users can open.
 
 ### Minimal cURL flow
 
@@ -200,7 +200,7 @@ curl -s "https://app.all-hands.dev/api/v1/app-conversations/start-tasks?ids=${ST
   -H "Authorization: Bearer ${OPENHANDS_CLOUD_API_KEY}"
 ```
 
-Then check execution status:
+Then check execution status and get the link to share (`conversation_ui_url`):
 
 ```bash
 curl -s "https://app.all-hands.dev/api/v1/app-conversations?ids=${APP_CONVERSATION_ID}" \
@@ -229,7 +229,7 @@ if not ready.get("app_conversation_id"):
     ready = api.poll_start_task_until_ready(start["id"])
 
 conversation_id = ready["app_conversation_id"]
-print(f"Delegated conversation: {api.base_url}/conversations/{conversation_id}")
+print(f"Delegated conversation: {api.app_conversation_ui_url(conversation_id)}")
 
 status = api.app_conversation_get(conversation_id)
 print(status.get("sandbox_status"), status.get("execution_status"))

package/plugins/openhands/skills/openhands-api/scripts/openhands_api.py

@@ -129,6 +129,19 @@ class OpenHandsAPI:
         items = self.app_conversations_get_batch(ids=[conversation_id])
         return items[0] if items else None
 
+    def app_conversation_ui_url(self, conversation_id: str) -> str:
+        """Browser link that opens the conversation in Agent Canvas.
+
+        Share this link with users. `conversation_url` on the conversation record is
+        the sandbox's agent-server API, not a page a user can open.
+        """
+        conversation = self.app_conversation_get(conversation_id) or {}
+        # Servers that predate `conversation_ui_url` serve Agent Canvas at /canvas.
+        return (
+            conversation.get("conversation_ui_url")
+            or f"{self.base_url}/canvas/conversations/{conversation_id}"
+        )
+
     def sandboxes_search(self, *, limit: int = 20) -> dict[str, Any]:
         limit = max(1, int(limit))
         r = self._client.get(f"{self.api_v1_url}/sandboxes/search", params={"limit": limit})

package/plugins/openhands/skills/openhands-automation/SKILL.md

@@ -47,7 +47,7 @@ The agent server typically runs inside a **sandbox** (a Docker or Kubernetes con
 | Variable | Availability | Description |
 |---|---|---|
 | `RUNTIME_URL` | Ambient in cloud environments | Public-facing URL of the **agent server** sandbox. Use this to determine whether external webhook delivery is possible — if unset or local, webhooks cannot be received. The automation service may run at a separate URL (see Determining the API Host). |
-| `AGENT_SERVER_URL` | Injected into scripts at run time only | Internal URL of the agent server. Available inside script execution context; **not** an ambient environment variable outside of a running script. |
+| `AGENT_SERVER_URL` | Injected into scripts at run time, local Agent Canvas only | Internal URL of the agent server. Available inside script execution context; **not** an ambient environment variable outside of a running script, and not set on OpenHands Cloud or Enterprise. |
 | `OPENHANDS_HOST` | Shell convention only — set manually | Base URL for the automation service API. **Not a real environment variable.** Set it from an explicit host, a detected local Agent Canvas server, or the cloud default. Used in all `curl` examples throughout this skill. |
 
 > **⚠️ CRITICAL — Agent behavior rules:**
@@ -77,17 +77,22 @@ The agent server typically runs inside a **sandbox** (a Docker or Kubernetes con
 
 ### No-LLM Script Helpers
 
-When building a deterministic custom script, these two stdlib-only functions are required. Copy them verbatim — they use `AGENT_SERVER_URL` and `SESSION_API_KEY` injected by the automation service.
+When building a deterministic custom script, these two stdlib-only functions are required. Copy them verbatim - they use variables injected by the automation service: `SESSION_API_KEY`, plus `AGENT_SERVER_URL` on a local Agent Canvas or `OPENHANDS_CLOUD_API_URL` and `SANDBOX_ID` on OpenHands Cloud and Enterprise.
 
 ```python
 import json, os, urllib.request
 
 def get_secret(name):
-    """Fetch a named secret stored in the agent server."""
+    """Fetch a named secret: from the agent server when AGENT_SERVER_URL is set, else from the OpenHands API."""
     url = os.environ.get("AGENT_SERVER_URL", "").rstrip("/")
     key = os.environ.get("SESSION_API_KEY") or os.environ.get("OH_SESSION_API_KEYS_0", "")
+    if url:  # local Agent Canvas
+        url = f"{url}/api/settings/secrets/{name}"
+    else:  # OpenHands Cloud / Enterprise
+        api = os.environ["OPENHANDS_CLOUD_API_URL"].rstrip("/")
+        url = f"{api}/api/v1/sandboxes/{os.environ['SANDBOX_ID']}/settings/secrets/{name}"
     with urllib.request.urlopen(urllib.request.Request(
-        f"{url}/api/settings/secrets/{name}", headers={"X-Session-API-Key": key}
+        url, headers={"X-Session-API-Key": key}
     )) as r:
         return r.read().decode().strip()
 
@@ -498,6 +503,7 @@ For services other than GitHub (Linear, Stripe, Slack, etc.), register a custom
 
 > **Agent behavior:**
 > - **Always provide the curl request** to the user — do not attempt to register webhooks yourself.
+>   The exception is a service skill that ships a setup script for its webhook, such as `jira-issue-to-pr`: the script registers both sides and keeps the signing secret out of the conversation, so run it as that skill describes.
 > - **Ask the user:** "Do you have a webhook signing secret from [service], or should the system generate one?"
 >   - If they have one → include `webhook_secret` in the request
 >   - If not → omit it; the response will contain a generated secret they must configure in their service
@@ -619,11 +625,67 @@ curl -X POST "${OPENHANDS_HOST}/api/automation/v1/preset/prompt" \
   }'
 ```
 
+### Custom Webhook Example: Jira Cloud
+
+Jira Cloud sends webhooks with:
+- Signature header: `X-Hub-Signature` (`sha256=` followed by the hex HMAC-SHA256 of the body), sent only when the webhook has a secret
+- Event type in payload: `webhookEvent` field (e.g., `jira:issue_created`, `jira:issue_updated`)
+- Labels as plain strings: `issue.fields.labels` is `["create-pr"]`, not a list of objects, so `issue.fields.labels[].name` matches nothing
+- On an update, a `changelog.items` list naming each changed `field`
+
+Only a webhook a Jira admin registers (Jira settings → System → WebHooks, or the REST API) can carry a secret. The "Send web request" action of a Jira Automation rule cannot sign its request, so it cannot deliver to a custom webhook.
+
+When the user can supply the API token of a Jira administrator, `scripts/setup_webhook.py` in the `jira-issue-to-pr` skill registers the webhook on both sides for them, replacing step 1 and the Jira configuration below. Done by hand:
+
+```bash
+# 1. Register the Jira webhook
+#    - Use "X-Hub-Signature" as the signature header
+#    - Use "webhookEvent" to extract the event type from the payload
+#    - Omit webhook_secret to have one generated, or pass the one Jira generated
+curl -X POST "${OPENHANDS_HOST}/api/automation/v1/webhooks" \
+  -H "Authorization: Bearer ${OPENHANDS_API_KEY}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Jira Cloud",
+    "source": "jira",
+    "event_key_expr": "webhookEvent",
+    "signature_header": "X-Hub-Signature"
+  }'
+
+# Response includes webhook_url and the generated webhook_secret - configure both in Jira:
+# Jira settings → System → WebHooks → Create a WebHook → paste the webhook_url and the
+# secret, then select the issue events. A JQL filter such as `labels = create-pr` keeps
+# unrelated issues from being sent at all.
+
+# 2. Create an automation for issues that receive a label
+#    The filter matches an issue created with the label and an update that changes the
+#    labels of an issue carrying it. Without the changelog check, every later edit of a
+#    labelled issue would start another run. It still fires when another label is added
+#    to or removed from an issue that carries the label, so have the prompt skip an
+#    issue that already has a pull request.
+curl -X POST "${OPENHANDS_HOST}/api/automation/v1/preset/prompt" \
+  -H "Authorization: Bearer ${OPENHANDS_API_KEY}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Jira Issues Labelled create-pr",
+    "prompt": "A Jira issue received the create-pr label. Read the issue from the event payload and open a pull request for it.",
+    "trigger": {
+      "type": "event",
+      "source": "jira",
+      "on": ["jira:issue_created", "jira:issue_updated"],
+      "filter": "contains(issue.fields.labels, '\''create-pr'\'') && (webhookEvent == '\''jira:issue_created'\'' || length(changelog.items[?field == '\''labels'\''] || `[]`) > `0`)"
+    }
+  }'
+```
+
+An unsigned request to the webhook URL answers `401 Missing signature header: X-Hub-Signature`; that is the webhook working, not a fault. `404 Unknown webhook source` means no webhook with that source is registered for the organization in the URL.
+
 ### Common Signature Headers by Service
 
 | Service | Signature Header | Event Key Expression |
 |---------|-----------------|---------------------|
 | Linear | `Linear-Signature` | `type` |
+| Jira Cloud | `X-Hub-Signature` | `webhookEvent` |
 | Stripe | `Stripe-Signature` | `type` |
 | Slack | `X-Slack-Signature` | `type` |
 | Twilio | `X-Twilio-Signature` | `type` |

package/plugins/openhands/skills/openhands-automation/references/custom-automation.md

@@ -223,7 +223,7 @@ Key points:
 - **Your script and its conversations share the same agent server.** There is no network hop to a remote service.
 - **Conversations are asynchronous.** You can fire one and continue, fire several concurrently, or start none at all (e.g. if your script fetches external data and decides no action is needed).
 - **The completion callback** is sent by `OpenHandsCloudWorkspace.__exit__` when the `with` block exits, telling the automation service the run is done. For async patterns, defer exiting until the conversation is in the desired state.
-- **Secrets** stored in the agent server are accessed via its REST API: `GET {AGENT_SERVER_URL}/api/settings/secrets/{name}` with `X-Session-API-Key: {SESSION_API_KEY}`. SDK scripts can also call `workspace.get_llm()` to get the configured LLM.
+- **Secrets** are fetched over REST with `X-Session-API-Key: {SESSION_API_KEY}`. When `AGENT_SERVER_URL` is set (local Agent Canvas): `GET {AGENT_SERVER_URL}/api/settings/secrets/{name}`. Otherwise (OpenHands Cloud and Enterprise): `GET {OPENHANDS_CLOUD_API_URL}/api/v1/sandboxes/{SANDBOX_ID}/settings/secrets/{name}`. SDK scripts can also call `workspace.get_llm()` to get the configured LLM.
 
 **SDK Documentation:** https://docs.openhands.dev/sdk
 
@@ -421,7 +421,7 @@ with OpenHandsCloudWorkspace(local_agent_server_mode=True, cloud_api_url=api_url
 
 For tasks that don't need AI reasoning — sending a Slack message, calling an API, rotating from a fixed list — skip the SDK entirely. Use pure Python stdlib with `python3 main.py` as the entrypoint and no `setup.sh`.
 
-**Accessing secrets** — custom secrets are not injected into the subprocess environment automatically. Fetch them via the agent server's REST API:
+**Accessing secrets** — custom secrets are not injected into the subprocess environment automatically. Fetch them over REST (from the agent server when `AGENT_SERVER_URL` is set, otherwise from the OpenHands API):
 
 ```python
 import os, urllib.request
@@ -429,8 +429,15 @@ import os, urllib.request
 def get_secret(name: str) -> str:
     url = os.environ.get("AGENT_SERVER_URL", "").rstrip("/")
     key = os.environ.get("SESSION_API_KEY") or os.environ.get("OH_SESSION_API_KEYS_0", "")
+    if url:
+        # Local Agent Canvas: secrets live in the agent server.
+        url = f"{url}/api/settings/secrets/{name}"
+    else:
+        # OpenHands Cloud / Enterprise: secrets live in the OpenHands API.
+        api = os.environ["OPENHANDS_CLOUD_API_URL"].rstrip("/")
+        url = f"{api}/api/v1/sandboxes/{os.environ['SANDBOX_ID']}/settings/secrets/{name}"
     req = urllib.request.Request(
-        f"{url}/api/settings/secrets/{name}",
+        url,
         headers={"X-Session-API-Key": key},
     )
     with urllib.request.urlopen(req) as r:
@@ -627,11 +634,13 @@ def save_state(state: dict) -> None:
 
 ## Environment Variables
 
-The automation service injects these environment variables into every run:
+The automation service injects these environment variables into every run, except where a row says otherwise:
 
 | Variable | Alt name | Description |
 |----------|----------|-------------|
-| `AGENT_SERVER_URL` | — | Agent server URL. Used as `cloud_api_url` for `OpenHandsCloudWorkspace`, and as the base URL for secret lookups |
+| `AGENT_SERVER_URL` | — | Agent server URL. Local Agent Canvas only; not set on OpenHands Cloud or Enterprise. Used as `cloud_api_url` for `OpenHandsCloudWorkspace`, and as the base URL for secret lookups |
+| `OPENHANDS_CLOUD_API_URL` | — | OpenHands API base URL. OpenHands Cloud and Enterprise only. Base URL for secret lookups |
+| `SANDBOX_ID` | — | ID of the sandbox the run executes in. OpenHands Cloud and Enterprise only. Part of the secret lookup URL |
 | `OH_SESSION_API_KEYS_0` | `SESSION_API_KEY` | Session API key. Used as `cloud_api_key` for `OpenHandsCloudWorkspace`, and as `X-Session-API-Key` for REST API calls |
 | `AUTOMATION_CALLBACK_URL` | — | POST here to mark the run complete (done automatically by `OpenHandsCloudWorkspace.__exit__`, or manually in no-LLM scripts) |
 | `AUTOMATION_CALLBACK_API_KEY` | — | Bearer token for the completion callback POST |
@@ -673,7 +682,12 @@ CHANNEL = "C12345678"
 def get_secret(name):
     url = os.environ.get("AGENT_SERVER_URL", "").rstrip("/")
     key = os.environ.get("SESSION_API_KEY") or os.environ.get("OH_SESSION_API_KEYS_0", "")
-    req = urllib.request.Request(f"{url}/api/settings/secrets/{name}",
+    if url:  # local Agent Canvas
+        url = f"{url}/api/settings/secrets/{name}"
+    else:  # OpenHands Cloud / Enterprise
+        api = os.environ["OPENHANDS_CLOUD_API_URL"].rstrip("/")
+        url = f"{api}/api/v1/sandboxes/{os.environ['SANDBOX_ID']}/settings/secrets/{name}"
+    req = urllib.request.Request(url,
         headers={"X-Session-API-Key": key})
     with urllib.request.urlopen(req) as r:
         return r.read().decode().strip()
@@ -823,7 +837,7 @@ The upload limit is 1MB. Reduce your tarball size by:
 ### Run fails instantly with `error_detail: null`
 The script sent `fire_callback("FAILED")` immediately — before doing meaningful work. Common causes:
 - A required secret was empty: the `get_secret()` call failed or returned nothing
-- A missing/wrong `AGENT_SERVER_URL` or `SESSION_API_KEY`
+- A missing/wrong `SESSION_API_KEY`, or a missing `OPENHANDS_CLOUD_API_URL` / `SANDBOX_ID` (`AGENT_SERVER_URL` on a local Agent Canvas)
 - An import error in the entrypoint
 
 Add `"error": str(exc)` to your `fire_callback("FAILED", ...)` call so `error_detail` is populated.

package/plugins/runtime-api-configs/.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "runtime-api-configs",
+  "version": "0.1.0",
+  "description": "Manage warm sandbox pools on OpenHands Enterprise by driving the runtime-api admin endpoints (list, save, delete warm runtime configurations) from a Python CLI. Standard-library only, runs anywhere python3 is available.",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "openhands-enterprise",
+    "runtime-api",
+    "warm-runtime-config",
+    "warm-pool",
+    "custom-sandbox-image",
+    "admin"
+  ]
+}

package/plugins/runtime-api-configs/.codex-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "runtime-api-configs",
+  "version": "0.1.0",
+  "description": "Manage warm sandbox pools on OpenHands Enterprise by driving the runtime-api admin endpoints (list, save, delete warm runtime configurations) from a Python CLI. Standard-library only, runs anywhere python3 is available.",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "openhands-enterprise",
+    "runtime-api",
+    "warm-runtime-config",
+    "warm-pool",
+    "custom-sandbox-image",
+    "admin"
+  ]
+}

package/plugins/runtime-api-configs/.plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "runtime-api-configs",
+  "version": "0.1.0",
+  "description": "Manage warm sandbox pools on OpenHands Enterprise by driving the runtime-api admin endpoints (list, save, delete warm runtime configurations) from a Python CLI. Standard-library only, runs anywhere python3 is available.",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "openhands-enterprise",
+    "runtime-api",
+    "warm-runtime-config",
+    "warm-pool",
+    "custom-sandbox-image",
+    "admin"
+  ]
+}

package/plugins/runtime-api-configs/README.md

@@ -0,0 +1,59 @@
+# runtime-api-configs
+
+Python CLI for managing warm sandbox pools on OpenHands Enterprise (OHE) via
+the `runtime-api` admin endpoints. This plugin supersedes the ad-hoc
+`warm-runtime-configs.sh` snippets embedded in the docs.
+
+- **Skill definition:** [`SKILL.md`](./SKILL.md)
+- **CLI:** [`scripts/warm_runtime_configs.py`](./scripts/warm_runtime_configs.py)
+- **Docs:** <https://docs.openhands.dev/enterprise/custom-sandbox-images/multiple-images-warm-pools>
+
+## Quick start
+
+Export the runtime-api URL and the admin password you set in the OHE Admin
+Console (VM installs) or that lives in the `admin-password` Kubernetes
+secret (Helm installs):
+
+```bash
+export RUNTIME_API_URL=https://runtime-api.<your-base-domain>
+export ADMIN_PASSWORD=<the-runtime-api-admin-password>
+```
+
+Then drive the CLI over HTTPS. No `kubectl`, no SSH:
+
+```bash
+# 1. Inspect the effective set
+python3 scripts/warm_runtime_configs.py list
+
+# 2. Register a new custom sandbox image
+python3 scripts/warm_runtime_configs.py template v1_current \
+  --image ghcr.io/your-org/openhands-php:8.4-v1 --count 1 \
+  | python3 scripts/warm_runtime_configs.py save php-web --file -
+
+# 3. Delete when finished
+python3 scripts/warm_runtime_configs.py delete php-web
+```
+
+If you would rather pull all three env vars from Kubernetes secrets in one
+step, see the `bootstrap` subcommand in [`SKILL.md`](./SKILL.md) - on
+Replicated VM installs it needs `sudo -E`; on Helm it needs
+`kubectl port-forward` and `--skip-url`.
+
+## Why a plugin instead of a shell script
+
+- **Runs anywhere Python 3.9+ is available.**
+- **No third-party dependencies** - pure stdlib (`urllib`, `hashlib`,
+  `argparse`).
+- **First-class `template` subcommand** replaces `jq` gymnastics when
+  deriving custom configurations from the installer default.
+- **Testable**: `tests/test_warm_runtime_configs.py` exercises the full
+  request/response path against an in-process HTTP server.
+
+## Development
+
+```bash
+python3 -m unittest discover -s tests
+```
+
+The tests spin up a stdlib `http.server` on an ephemeral port, so they need
+no cluster access.