Skip to content
Skills Library
DevOps & cloud · Tool integration

runtime-api-configs

/runtime-api-configs

Manage warm sandbox pools on OpenHands Enterprise by driving the runtime-api admin endpoints (list, save, delete warm runtime configurations) from a Python CLI. Use when an OpenHands Enterprise administrator asks to add, update, delete, or inspect custom sandbox images, warm pools, or `warm-runtime-configs`, or when the docs point to `enterprise/custom-sandbox-images/multiple-images-warm-pools`.

Repository
extensions ↗
Licence
MIT
Last repository change
25.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
7
Scripts
2
HTML comments
0
URLs in SKILL.md
7
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 2 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/warm_runtime_configs.py, tests/test_warm_runtime_configs.py

What it does and when to use it

Manage warm sandbox pools on OpenHands Enterprise by driving the runtime-api admin endpoints (list, save, delete warm runtime configurations) from a Python CLI. Use when an OpenHands Enterprise administrator asks to add, update, delete, or inspect custom sandbox images, warm pools, or `warm-runtime-configs`, or when the docs point to `enterprise/custom-sandbox-images/multiple-images-warm-pools`.

Original author 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. Use when an OpenHands Enterprise administrator asks to add, update, delete, or inspect custom sandbox images, warm pools, or `warm-runtime-configs`, or when the docs point to `enterprise/custom-sandbox-images/multiple-images-warm-pools`.

How it works

  1. When to use this skill
  2. Prerequisites
  3. Setup
  4. CLI reference
  5. Typical workflow
  6. After an OHE upgrade
  7. Environment variables
  8. Advanced: bootstrap from Kubernetes
  9. See also
Original SKILL.md headings · 224 lines, 1,249 words
SKILL.md preview
---
name: runtime-api-configs
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. Use when an OpenHands Enterprise administrator asks to add,
  update, delete, or inspect custom sandbox images, warm pools, or
  `warm-runtime-configs`, or when the docs point to
  `enterprise/custom-sandbox-images/multiple-images-warm-pools`.
triggers:
- warm-runtime-config
- warm runtime config
- warm pool
- warm-runtime-configs
- custom sandbox image
- runtime-api admin
---

# Runtime API - Warm Runtime Configurations

This plugin manages the warm sandbox pools used by OpenHands Enterprise. It
replaces the ad-hoc `warm-runtime-configs.sh` shell script embedded in the
docs and gives administrators a single, testable Python CLI for the same
workflow.

The CLI talks HTTP to the runtime-api service. It never modifies the cluster
directly, and it uses only the Python standard library, so it runs anywhere
`python3` is available.

## When to use this skill

Reach for this skill whenever the user wants to:

- **List** the effective warm-runtime configurations on an OHE install.
- **Add or update** a custom sandbox image (e.g. `openhands-php:8.4-v1`) so
  users can select it from the **Settings → Application → Default Sandbox**
  dropdown.
- **Delete** a database-managed configuration, restoring an installer-managed
  entry with the same name.
- **Refresh configurations after upgrading OHE**, when API-managed frozen
  snapshots need to be re-derived from the new installer template.
- **Bootstrap credentials** (`RUNTIME_API_URL`, `API_KEY`, `ADMIN_PASSWORD`)
  from Kubernetes secrets so subsequent runs need no cluster access.

If the user is instead asking how to **build** a custom sandbox image
(Dockerfile, versioning), point them at
[Building a Custom Image](https://docs.openhands.dev/enterprise/custom-sandbox-images/building-custom-images)
- image building is out of scope for this skill.

## Prerequisites

- OpenHands Enterprise **0.64.0 or later**.
- Python **3.9+** on the machine running the CLI. No third-party packages.
- The **Runtime API Admin Password**:
  - **VM (Replicated) installs**: set via *Admin Console → Config → Sandbox
    Configuration → Runtime API Admin Password*.
  - **Helm installs**: the value stored in the `admin-password` Kubernetes
    secret in the runtime-api namespace. Helm has no Admin Console.
- **Helm installs only**: the runtime-api chart must be running in **overlay
  mode** and have warm pools enabled, so `v1_current` shows up in `list` and
  can be used as a `template` source. Set both in your umbrella values:

  ```yaml
  runtime-api:
    warmRuntimes:
      enabled: true
    env:
      WARM_RUNTIME_CONFIG_OVERLAY: "1"
  ```

  Overlay mode is on by default on Replicated VM installs. Without it on
  Helm, `list` returns `[]` on a fresh install and `template v1_current`
  fails.

## Setup

On any machine with HTTPS reachability to the runtime-api, export two env
vars:

```bash
export RUNTIME_API_URL=https://runtime-api.<your-base-domain>
export ADMIN_PASSWORD=<runtime-api-admin-password>   # see Prerequisites above
```

That is the full setup on any install where the runtime-api ingress is
reachable from the machine running the CLI. No `kubectl`, no SSH, no
cluster access. If the runtime-api is cluster-internal (Helm default), see
the Helm entry in the Advanced section below to port-forward first.

Under the hood, the CLI uses the admin password directly for `save` and
`delete` (via the PBKDF2 handshake), and for `list` and `template` it logs
in as admin and fetches the `default` read-only API key over HTTPS from
`/api/admin/api-keys`.

If you already know the read-only API key (for example, from an operator
runbook), export it too and the CLI will skip the extra admin-login round
trip on reads:

```bash
export API_KEY=<default api key>
```

If you have `kubectl` access to the cluster and prefer to pull all three
env vars from Kubernetes secrets in one step, see
**[Advanced: bootstrap from Kubernetes](#advanced-bootstrap-from-kubernetes)**
at the bottom of this file.

## CLI reference

Run with `python3 scripts/warm_runtime_configs.py <subcommand>`. Each
subcommand exits non-zero on error and prints the runtime-api's HTTP body
on failure.

| Subcommand | Auth | Purpose |
|---|---|---|
| `list` | `API_KEY` if set, else admin login | Print the effective set of configurations. |
| `template <source>` | `API_KEY` if set, else admin login | Fetch a config, strip identity fields, override image/count, print JSON ready to `save`. |
| `save <name> [--file F]` | Admin password | Upsert a configuration. Reads JSON from `--file` or stdin. |
| `delete <name>` | Admin password | Delete a database-managed configuration. |
| `bootstrap` | kubectl | Print `export` lines for `RUNTIME_API_URL`, `API_KEY`, `ADMIN_PASSWORD`. Optional; see [Advanced](#advanced-bootstrap-from-kubernetes) below. |

Full help: `python3 scripts/warm_runtime_configs.py --help` and
`python3 scripts/warm_runtime_configs.py <subcommand> --help`.

## Typical workflow

Register a new PHP sandbox image once credentials are in the environment:

```bash
# 1. Derive a config JSON from the current default, changing only the image
python3 scripts/warm_runtime_configs.py template v1_current \
  --image ghcr.io/your-org/openhands-php:8.4-v1 --count 1 \
  --output php-web.json

# 2. Save it
python3 scripts/warm_runtime_configs.py save php-web --file php-web.json

# 3. Confirm
python3 scripts/warm_runtime_configs.py list
```

Within about a minute the pool is ready and `php-web` appears in
**Settings → Application → Default Sandbox**.

Deleting an API-managed configuration removes it from the effective set:

```bash
python3 scripts/warm_runtime_configs.py delete php-web
```

`delete` operates on database rows only, so it 404s for names that have
never been saved through this CLI (installer-managed entries like
`v1_current` on a fresh install fall in that bucket). In overlay mode, if
you had previously saved a database row that shadowed a same-named
ConfigMap entry, deleting the row reverts to the ConfigMap entry on the
next reconciler cycle.

## After an OHE upgrade

Frozen API-managed configurations do not follow release bumps. After every
OHE upgrade, re-derive each API-managed configuration from the refreshed
default template, keeping each configuration's current image tag and pool
size unless you deliberately change them:

```bash
# One "name image count" tuple per API-managed config; edit for your fleet.
# Preserving the existing pool count matters: hardcoding it would silently
# shrink pools on every refresh.
while read -r name image count; do
  [ -z "$name" ] && continue
  python3 scripts/warm_runtime_configs.py template v1_current \
    --image "$image" --count "$count" \
    | python3 scripts/warm_runtime_configs.py save "$name" --file -
done <<'EOF'
php-web        ghcr.io/your-org/openhands-php:8.4-v2    3
ruby-app       ghcr.io/your-org/openhands-ruby:3.3-v2   2
node-monorepo  ghcr.io/your-org/openhands-node:24-v2    1
EOF
```

Two caveats worth spelling out:

- `template` refreshes the *command* and *environment* to match the new
  `v1_current`, but it keeps whatever image tag you pass. To actually
  pick up a new agent-server version, the image itself must be rebuilt
  against the matching agent-server base. This loop alone does not do
  that.
- Skipping this step leaves configurations pointing at the previous
  agent-server command/environment, and new conversations fail with a
  version mismatch until the configurations are updated.

## Environment variables

| Variable | Used by | Notes |
|---|---|---|
| `RUNTIME_API_URL` | all HTTP subcommands | e.g. `https://runtime-api.example.com` or `http://localhost:5000`. |
| `ADMIN_PASSWORD` | `save`, `delete`; also `list`/`template` when `API_KEY` is unset | Runs the PBKDF2 challenge-response handshake. |
| `ADMIN_TOKEN` | Anywhere `ADMIN_PASSWORD` is used | Pre-obtained admin JWT. When set, it wins over `ADMIN_PASSWORD` and skips the handshake. |
| `API_KEY` | `list`, `template` (optional) | Sent as `X-API-Key`. Optional: when unset, the CLI fetches the `default` key over HTTPS via admin login. |
| `NAMESPACE` | `bootstrap` | Defaults to `openhands`. Overridable via `--namespace`. |

## Advanced: bootstrap from Kubernetes

`bootstrap` extracts all three env vars from Kubernetes secrets in one
step. Handy for cluster operators and CI, but the default HTTPS-only
workflow above is preferred for interactive admin use.

### VM (Replicated) install

The k0s kubeconfig is root-owned, so the invocation runs under sudo:

```bash
eval "$(sudo -E python3 scripts/warm_runtime_configs.py bootstrap --namespace openhands)"
```

### Helm install

The runtime-api is cluster-internal on Helm (chart default is
`ingress.enabled: false`). The Kubernetes service name is release-prefixed
via `include "runtime-api.fullname"`, so it is not literally `runtime-api`
- discover it and port-forward, then bootstrap without touching
`RUNTIME_API_URL`:

```bash
SVC=$(kubectl -n openhands get svc \
  -l app.kubernetes.io/name=runtime-api \
  -o jsonpath='{.items[0].metadata.name}')
kubectl -n openhands port-forward "svc/$SVC" 5000:5000 &
export RUNTIME_API_URL=http://localhost:5000
eval "$(python3 scripts/warm_runtime_configs.py bootstrap --namespace openhands --skip-url)"
```

`--skip-url` leaves `RUNTIME_API_URL` alone. If the operator set
`nameOverride` on the runtime-api subchart, adjust the label selector to
match.

## See also

- Docs: [Configuring Custom Sandbox Images](https://docs.openhands.dev/enterprise/custom-sandbox-images/multiple-images-warm-pools)
- Docs: [Using Custom Images](https://docs.openhands.dev/enterprise/custom-sandbox-images/using-custom-images)
Files in this package (7)
  • .claude-plugin 1 KB
  • .codex-plugin 1 KB
  • README.md 2 KB
  • SKILL.md 10 KB
  • .plugin/plugin.json 1 KB
  • scripts/warm_runtime_configs.py 11 KB
  • tests/test_warm_runtime_configs.py 12 KB

Versions

The database has no other skills named runtime-api-configs.

Database snapshot: 13.11.2026 · package version 65b80aeba847 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100openhands-enterprise-troubleshooting
    This skill should be used when a user reports an issue with OpenHands Enterprise (OHE) on a self-hosted (Replicated VM-based) installation. Use for diagnosing sandbox startup failures, auth issues, certificate errors, LLM connectivity problems, Keycloak login issues, Replicated…
  • 100openhands
    Unified OpenHands plugin — bundles the OpenHands Cloud CLI, Cloud REST API (openhands-api), Automations (openhands-automation), and Software Agent SDK reference (openhands-sdk) into a single plugin. Use this when you need to interact with OpenHands Cloud or build agents with the SDK.
  • 87huawei-cloud-swr-enterprise-instance
    Huawei Cloud SWR enterprise instance management skill using hcloud CLI. Use this skill when the user wants to: (1) manage SWR enterprise instances - create/list/show/delete/update configuration, (2) manage instance namespaces - create/list/show/update/delete with security…
  • 100openhands-sdk
    Reference skill for the OpenHands Software Agent SDK - the Python framework for building AI agents that write software. Use when you need to build agents with the SDK, create custom tools, configure LLMs, manage conversations, delegate to sub-agents, or deploy agents locally or remotely.
  • 90vercel-sandbox
    Investigate Vercel Sandbox lifecycle, timeout, snapshot, and persistence behavior. Use when users ask about Vercel Sandbox, `@vercel/sandbox`, `Sandbox.create`, `Sandbox.get`, why files disappeared, how snapshots differ from persistence, or whether Vercel's persistent sandbox beta applies.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.