/serve-openpi-policy

name: serve-openpi-policy
description: Starts, reuses, verifies, and explicitly stops the local Dockerized OpenPI inference server used by Isaac Lab-Arena Pi0RemotePolicy experiments. Use when serving pi05 or pi0 locally, selecting an OpenPI port or variant, checking whether the OpenPI server is ready, handling an OpenPI server conflict, or when run-experiment discovers a local OpenPI policy dependency. Do not use for running Experiment Definitions, OSMO submission, other policy providers, training, or general Arena container setup.
allowed-tools: Read Grep Glob Skill Bash(git rev-parse --show-toplevel) Bash(test -x isaaclab_arena_openpi/docker/run_openpi_server.sh) Bash(docker images -q isaaclab_arena:openpi_server) Bash(docker logs *) Bash(docker ps *) Bash(ss -ltn *) Bash(./isaaclab_arena_openpi/docker/run_openpi_server.sh *)

Serve OpenPI Policy

Start one local OpenPI inference server and finish with a verified endpoint for an Arena `Pi0RemotePolicy` client. Keep Experiment execution, artifacts, OSMO, and other policy providers outside this skill.

Read the checked-out workflow

Before acting, read:

• `docs/pages/quickstart/running_a_real_policy/openpi.rst` for the maintained two-terminal workflow,

first-run costs, and readiness message.

• `isaaclab_arena_openpi/docker/run_openpi_server.sh` for the supported flags and current variant

mapping.

Treat the current checkout as the source of truth. Use the wrapper rather than reconstructing its Docker command or calling `build_server_image.sh` directly. Report any mismatch between this skill, the documentation, and the wrapper.

Resolve the requested endpoint

1. Confirm the repository root and executable wrapper. 2. Resolve the variant and port from the request or the Experiment's policy configuration. Use `pi05` and port `8000` only when neither source specifies them. 3. Accept only variants supported by the wrapper: `pi05` or `pi0`. Require an integer port from 1 through 65535. 4. Serve only a loopback client endpoint such as `127.0.0.1` or `localhost`. If an Experiment names another host, treat it as an external server dependency and return control to `run-experiment`; do not start an unrelated local server.

When called by `run-experiment`, identify OpenPI from the resolved policy type `isaaclab_arena_openpi.policy.pi0_remote_policy.Pi0RemotePolicy` or its registered name `pi0_remote`, not from the Experiment filename. Match the server's variant and port to the policy configuration. If Runs request different variants on the same port, stop and ask the user to choose separate ports or one variant.

Reuse a compatible server

Inspect before launching:

docker images -q isaaclab_arena:openpi_server
docker ps --no-trunc --filter ancestor=isaaclab_arena:openpi_server \
  --format '{{.ID}}\t{{.Names}}\t{{.Command}}'
ss -ltn

The wrapper assigns a random container name, so never identify a server by a hardcoded name. For each candidate, use its full command to match the selected port and the variant-specific policy configuration, then use `docker logs <exact-container>` to require this maintained readiness line for the selected port:

INFO:websockets.server:server listening on 0.0.0.0:<port>

Reuse the server only when the container is still running, its variant and port match, and its logs show readiness. A listening TCP port alone is insufficient evidence that it speaks the OpenPI protocol. If the selected port is occupied by an incompatible server or another process, do not stop it. Report the conflict and ask whether to select a different port or explicitly stop its owner.

Disclose first-run work

Read the current build-time, image-size, and checkpoint-download estimates from the checked-out OpenPI workflow and disclose them before a missing-image or uncached-variant launch. Obtain confirmation before starting that large build or download. Do not rely on copied estimates when the checked-out documentation has newer values.

Use `-r` only when the user explicitly requests a forced rebuild and confirms it. Do not push an image, run a no-cache build, clear caches, or install or change Docker, GPU drivers, or the NVIDIA Container Toolkit through this skill.

Launch and verify

Start the wrapper from the repository root in a retained terminal session that runs asynchronously from this workflow. Keep the wrapper in the foreground of that session, record the returned session or task handle, and pass the resolved values explicitly so the effective server matches the Experiment:

./isaaclab_arena_openpi/docker/run_openpi_server.sh -v <pi05-or-pi0> -p <port>

Retain the terminal session handle and poll its output without waiting for the command to finish; the command is expected to remain active for the server's lifetime. Do not append `&`, use `nohup`, or replace the wrapper with a detached Docker command. Do not report readiness until the wrapper remains running and emits the readiness line for the selected port. After readiness, leave that session active while returning control to `run-experiment`.

The wrapper owns the image build, host-network Docker launch, GPU access, checkpoint cache, and cache-ownership cleanup; do not duplicate those operations.

On failure, preserve and report the wrapper output. Do not silently rebuild, change variants or ports, stop another process, or retry with different settings.

Hand off the endpoint

Return the variant, loopback host, port, readiness evidence, exact container identity, and retained terminal session handle when this workflow started the server. If `run-experiment` requested the server, return control to it while the retained session remains active so it can execute the Experiment and verify artifacts. Do not invoke the Experiment Runner here.

When the selected variant or port differs from the Experiment configuration, provide every corresponding per-Run Hydra override so the client and server remain compatible, f