Agent skill

Runtime API Configs

by OpenHands in OpenHands/extensions

Manage warm sandbox pools on OpenHands Enterprise by driving the runtime-api admin endpoints (list, save, delete warm runtime configurations) from a Python CLI.

MITAuto-check: notesDevOps & Cloud

Install Runtime API Configs

skills CLI
$ npx skills add OpenHands/extensions --skill runtime-api-configs -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install OpenHands/extensions runtime-api-configs --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/OpenHands/extensions.git skills-src && mkdir -p .claude/skills && cp -r skills-src/plugins/runtime-api-configs .claude/skills/runtime-api-configs && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
runtime-api-configs
GitHub stars
157
Token cost
~2.5k tokens
SKILL.md length
973 words
Files
7 (incl. scripts)
Skills in repo
78
Repo updated
First seen
Licence
MIT

At a glance

Manage warm sandbox pools on OpenHands Enterprise by driving the runtime-api admin endpoints (list, save, delete warm runtime configurations) from a Python CLI.

  • An OpenHands Enterprise administrator asks to add
  • SKILL.md covers When to use this skill, Prerequisites, Setup and CLI reference, plus 5 more sections
  • Runs Python scripts from its folder; calls python3 and kubectl; needs API_KEY and ADMIN_PASSWORD
  • Inspect custom sandbox images

What it does

Runtime API Configs is an agent skill from OpenHands/extensions. 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.

Its SKILL.md is about 2.5k tokens, which your agent loads only when the skill is triggered. The skill folder holds 9 other files, including scripts (for example `.plugin/plugin.json`, `README.md` and `scripts/warm_runtime_configs.py`).

It sits in DevOps & Cloud. It works with Python. The repository describes itself as: Public registry for OpenHands extensions. The licence is MIT.

When your agent uses it

  • An OpenHands Enterprise administrator asks to add
  • Inspect custom sandbox images
  • Warm-runtime-configs
  • The docs point to enterprise/custom-sandbox-images/multiple-images-warm-pools

Example prompts

  • “/runtime-api-configs”

Requirements

  • Python 3
  • A credential in API_KEY
  • A credential in ADMIN_TOKEN

What it can do on your machine

Read from SKILL.md and the folder at commit d008b81. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 1 file in scripts/ (Python), which the agent can run.

    Shell commands in SKILL.md call:

    • python3
    • kubectl

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Links to these hosts (documentation or services it may open):

    • docs.openhands.dev

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names these keys or tokens, usually read from environment variables:

    • API_KEY
    • ADMIN_PASSWORD
    • ADMIN_TOKEN

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Runtime API Configs loads about 2.5k tokens when it runs. Until then it costs about 105 tokens; SKILL.md has 973 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~105
When it runs · the whole SKILL.md, loaded when a task matches
~2.5k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check: notes

The automated check noted patterns worth knowing about, such as sudo or a known installer.

  • NoteRuns commands with sudoSKILL.md:213
    eval "$(sudo -E python3 scripts/warm_runtime_configs.py bootstrap --namespace openhands)"

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from OpenHands/extensions at commit d008b81, republished under its MIT licence (© OpenHands). 973 words, ~2,468 tokens.

Download SKILL.mdSave it as .claude/skills/runtime-api-configs/SKILL.md (or your agent's skills folder). This skill also uses 6 other files; get the full folder from GitHub.
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

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

SubcommandAuthPurpose
listAPI_KEY if set, else admin loginPrint the effective set of configurations.
template <source>API_KEY if set, else admin loginFetch a config, strip identity fields, override image/count, print JSON ready to save.
save <name> [--file F]Admin passwordUpsert a configuration. Reads JSON from --file or stdin.
delete <name>Admin passwordDelete a database-managed configuration.
bootstrapkubectlPrint export lines for RUNTIME_API_URL, API_KEY, ADMIN_PASSWORD. Optional; see Advanced below.

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

Show full SKILL.md (404 more words)Show less

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

VariableUsed byNotes
RUNTIME_API_URLall HTTP subcommandse.g. https://runtime-api.example.com or http://localhost:5000.
ADMIN_PASSWORDsave, delete; also list/template when API_KEY is unsetRuns the PBKDF2 challenge-response handshake.
ADMIN_TOKENAnywhere ADMIN_PASSWORD is usedPre-obtained admin JWT. When set, it wins over ADMIN_PASSWORD and skips the handshake.
API_KEYlist, template (optional)Sent as X-API-Key. Optional: when unset, the CLI fetches the default key over HTTPS via admin login.
NAMESPACEbootstrapDefaults 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

© OpenHands, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 6 other files (scripts) in plugins/runtime-api-configs of OpenHands/extensions.

  • SKILL.md
  • .claude-plugin
  • .codex-plugin
  • .plugin/plugin.json
  • README.md
  • scripts/warm_runtime_configs.py
  • tests/test_warm_runtime_configs.py

Open the folder on GitHubat commit d008b81

Compare with similar skills

Runtime API Configs next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Runtime API Configs compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Runtime API Configs this skillOpenHands/extensions157—~2.5kAutomated safety check: NotesMIT
AWS Cdk Developmentzxkane/aws-skills3672 repos~2.5kAutomated safety check: PassMIT
Reproduce macOS Python FlavorsNuitka/Nuitka15k—~1.7kAutomated safety check: PassAGPL-3.0
Env Var Conventionssgl-project/sglang37k2 repos~2.9kAutomated safety check: PassApache-2.0
Pymobiledevice3 Device Operatordoronz88/pymobiledevice32.8k—~1.8kAutomated safety check: NotesGPL-3.0
Vetatilladeniz/Kubeli3872 repos~1.6kAutomated safety check: PassMIT

Similar skills

  • AWS Cdk Development

    zxkane/aws-skills

    AWS Cloud Development Kit (CDK) expert for building cloud infrastructure with TypeScript/Python.

    367 GitHub starsUsed in 2 repos~2.5k tokens
    DevOps & CloudAuto-check passed
  • Reproduce macOS Nuitka issues across Python distributions and GitHub Actions Python packaging.

    15k GitHub stars~1.7k tokensUpdated today
    DevOps & CloudAuto-check passed
  • Env Var Conventions

    sgl-project/sglang

    Conventions for SGLang environment variables — where to define, how to access, how to name, and how to deprecate.

    37k GitHub starsUsed in 2 repos~2.9k tokens
    DevOps & CloudAuto-check passed
  • Pymobiledevice3 Device Operator

    doronz88/pymobiledevice3

    Operate iOS and iPadOS devices with pymobiledevice3, from a local checkout or straight from PyPI via uvx on a fresh workstation.

    2.8k GitHub stars~1.8k tokensUpdated today
    DevOps & CloudAuto-check: notes
  • Vet

    atilladeniz/Kubeli

    Run vet immediately after ANY logical unit of code changes. An agent skill from atilladeniz/Kubeli.

    387 GitHub starsUsed in 2 repos~1.6k tokens
    DevOps & CloudAuto-check passed
  • Statem

    henryqin1997/statem

    A skill your agent uses when a long coding or research task should be managed with statem state-machine runbooks, including creating specs, starting or resuming runs, checking current state…

    1.3k GitHub stars~1.2k tokensUpdated 1 mo ago
    DevOps & CloudAuto-check passed

More from OpenHands/extensions

All 78 skills in this repo
  • Agent Readiness Report

    OpenHands/extensions

    Evaluate how well a codebase supports autonomous AI-assisted development.

    157 GitHub stars~1.1k tokensUpdated today
    Auto-check passed
  • Discord

    OpenHands/extensions

    Build and automate Discord integrations (bots, webhooks, slash commands, and REST API workflows).

    157 GitHub stars~1.1k tokensUpdated today
    Auto-check passed
  • GitHub

    OpenHands/extensions

    Interact with GitHub repositories, pull requests, issues, and workflows using the GITHUBTOKEN environment variable and GitHub CLI.

    157 GitHub stars~1.7k tokensUpdated today
    Auto-check passed
  • GitHub Issue To PR

    OpenHands/extensions

    Create an automation that implements GitHub issues when a configurable trigger label is applied.

    157 GitHub stars~4.4k tokensUpdated today
    Auto-check passed
  • GitHub Repo Monitor

    OpenHands/extensions

    This skill should be used when the user asks to "monitor a GitHub repository", "watch GitHub for issues or PRs", "respond to @OpenHands mentions on GitHub", "set up an OpenHands GitHub integration"…

    157 GitHub stars~3.1k tokensUpdated today
    Auto-check passed
  • GitLab Issue To Mr

    OpenHands/extensions

    Create an automation that implements GitLab issues when a configurable trigger label is applied.

    157 GitHub stars~4.9k tokensUpdated today
    Auto-check passed

Works with

Categories

Questions about Runtime API Configs

What does Runtime API Configs do?

Manage warm sandbox pools on OpenHands Enterprise by driving the runtime-api admin endpoints (list, save, delete warm runtime configurations) from a Python CLI. Runtime API Configs is an agent skill from OpenHands/extensions. Manage warm sandbox pools on OpenHands Enterprise by driving the runtime-api admin endpoints (list, save, delete warm runtime configurations) from a Python CLI.

When should I use Runtime API Configs?

Runtime API Configs fits situations like: an OpenHands Enterprise administrator asks to add; inspect custom sandbox images; warm-runtime-configs; the docs point to enterprise/custom-sandbox-images/multiple-images-warm-pools.

How do I install Runtime API Configs in Claude Code?

Run `npx skills add OpenHands/extensions --skill runtime-api-configs -a claude-code`. Or copy the skill folder (plugins/runtime-api-configs in OpenHands/extensions) into .claude/skills/runtime-api-configs in your project. Claude Code loads it when a task matches its description.

How do I install Runtime API Configs in Codex?

Run `npx skills add OpenHands/extensions --skill runtime-api-configs -a codex`. Or copy the skill folder (plugins/runtime-api-configs in OpenHands/extensions) into .agents/skills/runtime-api-configs in your project. Codex loads it when a task matches its description.

Can I use Runtime API Configs in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add OpenHands/extensions --skill runtime-api-configs -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/runtime-api-configs, .gemini/skills/runtime-api-configs, .github/skills/runtime-api-configs and .opencode/skills/runtime-api-configs in your project.

What does Runtime API Configs need to run?

Going by SKILL.md and its folder, Runtime API Configs needs Python for the scripts in its folder, the command-line tools its instructions call (python3 and kubectl) and credentials named API_KEY, ADMIN_PASSWORD and ADMIN_TOKEN. Our summary lists: Python 3; A credential in API_KEY; A credential in ADMIN_TOKEN.

Does Runtime API Configs access the network?

SKILL.md names 1 domain. As links in the text: docs.openhands.dev. This is read from the text; nothing was executed.

Is Runtime API Configs safe to install?

Our automated static check of SKILL.md found notes only (runs commands with sudo), nothing it rates as a warning. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Runtime API Configs use?

Runtime API Configs is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Runtime API Configs use?

About 2.5k tokens (SKILL.md is roughly 9.9k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Runtime API Configs?

Skills that share tags, products or a category with Runtime API Configs: AWS Cdk Development (zxkane/aws-skills, 367 stars), Reproduce macOS Python Flavors (Nuitka/Nuitka, 15k stars), Env Var Conventions (sgl-project/sglang, 37k stars) and Pymobiledevice3 Device Operator (doronz88/pymobiledevice3, 2.8k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Runtime API Configs?

OpenHands (a GitHub organization) maintains it in OpenHands/extensions, which has 157 GitHub stars. The repository holds 78 skills in this directory. The repository was last updated on October 6, 2026.

Source: OpenHands/extensions on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.