Przejdź do treści
Biblioteka skilli
DevOps i chmura · Integracja z narzędziem

runtime-api-configs

/runtime-api-configs

Zarządza pulami rozgrzanych sandboxów w OpenHands Enterprise przez punkty administracyjne runtime-api z CLI Pythona: wylistowanie, zapis i usuwanie konfiguracji warm-runtime-configs.

Repozytorium
extensions ↗
Licencja
MIT
Ostatnia zmiana repozytorium
25.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
7
Skrypty
2
Komentarze HTML
0
Adresy URL w SKILL.md
7
Przestarzałość

Brak sygnałów. Repozytorium zmienione 25.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co sprawdzić przed instalacją
  • 2 skrypty w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.

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

Co robi i kiedy

Zarządza pulami rozgrzanych sandboxów w OpenHands Enterprise przez punkty administracyjne runtime-api z CLI Pythona: wylistowanie, zapis i usuwanie konfiguracji warm-runtime-configs.

Oryginalny opis (EN)

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`.

Jak działa

  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
Sekcje z nagłówków SKILL.md, w oryginale · 224 linii, 1 249 słów
Podgląd SKILL.md
---
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)
Pliki w paczce (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

Wersje

W bazie nie ma innych skilli o nazwie runtime-api-configs.

Migawka bazy z 13.11.2026 · wersja paczki 65b80aeba847 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100openhands-enterprise-troubleshooting
    Diagnozuje problemy OpenHands Enterprise na instalacji samodzielnie hostowanej w Replicated: start sandboxów, uwierzytelnianie, certyfikaty, łączność z LLM, logowanie Keycloak, aktualizacje i wyczerpanie zasobów.
  • 100openhands
    Łączy w jednej wtyczce CLI OpenHands Cloud, REST API, Automations i dokumentację Software Agent SDK, do pracy z OpenHands Cloud i budowania agentów.
  • 87huawei-cloud-swr-enterprise-instance
    Zarządza instancjami korporacyjnymi Huawei Cloud SWR przez hcloud: przestrzeniami nazw ze skanowaniem bezpieczeństwa, rejestrami synchronizacji i repozytoriami, w tym tworzenie, listowanie, zmiana i usuwanie.
  • 100openhands-sdk
    Pomaga budować agentów w SDK OpenHands w Pythonie: tworzy narzędzia, konfiguruje modele, prowadzi rozmowy i deleguje zadania.
  • 90vercel-sandbox
    Bada cykl życia, timeouty, snapshoty i trwałość Vercel Sandbox, w tym Sandbox.create i Sandbox.get, przyczyny znikania plików i działanie bety trwałych sandboxów.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.