Deprecate RUNTIME_URL in favor of OH_WEB_URL

[enyst]

Summary

Deprecate the legacy RUNTIME_URL environment variable and prefer OH_WEB_URL for resolving Config.web_url, while keeping the old variable as a fallback through v1.18.0 (five minor releases from v1.13.x).

Changes

• Prefer OH_WEB_URL when resolving Config.web_url
• Keep RUNTIME_URL as a fallback for backward compatibility
• Emit a deprecation warning when RUNTIME_URL is used as the fallback
• Document removal target in code via removed_in="1.18.0"
• Add tests for:
  • OH_WEB_URL resolution
  • RUNTIME_URL fallback warning
  • precedence when both env vars are set
  • explicit constructor override

Why

PR #2423 introduced RUNTIME_URL compatibility so path-based OpenAPI docs would keep working without updating downstream runtime integration immediately. Since we plan to remove that legacy env var, we should deprecate it explicitly rather than leave only a TODO.

This keeps compatibility today while making the preferred configuration path clear:

• preferred: OH_WEB_URL
• deprecated fallback: RUNTIME_URL

Validation

• uv run pre-commit run --files openhands-agent-server/openhands/agent_server/config.py tests/agent_server/test_api.py
• uv run pytest tests/agent_server/test_api.py

Reference

• Introduced compatibility: Fix broken OpenAPI docs in with path based routing #2423

---

Agent Server images for this PR

• GHCR package: https://github.com/OpenHands/agent-sdk/pkgs/container/agent-server

Variants & Base Images

Variant	Architectures	Base Image	Docs / Tags
java	amd64, arm64	eclipse-temurin:17-jdk	Link
python	amd64, arm64	nikolaik/python-nodejs:python3.13-nodejs22	Link
golang	amd64, arm64	golang:1.21-bookworm	Link

Pull (multi-arch manifest)

# Each variant is a multi-arch manifest supporting both amd64 and arm64
docker pull ghcr.io/openhands/agent-server:1d57896-python

Run

docker run -it --rm \
  -p 8000:8000 \
  --name agent-server-1d57896-python \
  ghcr.io/openhands/agent-server:1d57896-python

All tags pushed for this build

ghcr.io/openhands/agent-server:1d57896-golang-amd64
ghcr.io/openhands/agent-server:1d57896-golang_tag_1.21-bookworm-amd64
ghcr.io/openhands/agent-server:1d57896-golang-arm64
ghcr.io/openhands/agent-server:1d57896-golang_tag_1.21-bookworm-arm64
ghcr.io/openhands/agent-server:1d57896-java-amd64
ghcr.io/openhands/agent-server:1d57896-eclipse-temurin_tag_17-jdk-amd64
ghcr.io/openhands/agent-server:1d57896-java-arm64
ghcr.io/openhands/agent-server:1d57896-eclipse-temurin_tag_17-jdk-arm64
ghcr.io/openhands/agent-server:1d57896-python-amd64
ghcr.io/openhands/agent-server:1d57896-nikolaik_s_python-nodejs_tag_python3.13-nodejs22-amd64
ghcr.io/openhands/agent-server:1d57896-python-arm64
ghcr.io/openhands/agent-server:1d57896-nikolaik_s_python-nodejs_tag_python3.13-nodejs22-arm64
ghcr.io/openhands/agent-server:1d57896-golang
ghcr.io/openhands/agent-server:1d57896-java
ghcr.io/openhands/agent-server:1d57896-python

About Multi-Architecture Support

• Each variant tag (e.g., 1d57896-python) is a multi-arch manifest supporting both amd64 and arm64
• Docker automatically pulls the correct architecture for your platform
• Individual architecture tags (e.g., 1d57896-python-amd64) are also available if needed

[github-actions]

Python API breakage checks — ✅ PASSED

Result: ✅ PASSED

Action log

[github-actions]

REST API breakage checks (OpenAPI) — ❌ FAILED

Result: ❌ FAILED

⚠️ Breaking REST API changes or policy violations detected.

Log excerpt (first 1000 characters)

::error title=openhands-agent-server REST API::Breaking REST API change detected without MINOR version bump (1.14.0 -> 1.14.0).

Breaking REST API changes detected compared to baseline release:
- added '#/components/schemas/ACPAgent-Output, #/components/schemas/Agent-Output' to the '/items/anyOf[subschema #1: ConversationInfo]/agent' response property 'oneOf' list for the response status '200'
- the '/items/anyOf[subschema #1: ConversationInfo]/agent' response's property type/format changed from 'object'/'' to ''/'' for status '200'
- removed the required property '/items/anyOf[subschema #1: ConversationInfo]/agent/kind' from the response with the '200' status
- removed the required property '/items/anyOf[subschema #1: ConversationInfo]/agent/llm' from the response with the '200' status
- the 'agent' request property type/format changed from 'object'/'' to ''/''
- added '#/components/schemas/ACPAgent-Output, #/components/schemas/Agent-Output' to the 'agent' response property 'oneOf' li

Action log

[github-actions]

Coverage Report •

File	Stmts	Miss	Cover	Missing
openhands-agent-server/openhands/agent_server
config.py	74	3	95%	31, 44, 205
TOTAL	20295	9131	55%

[all-hands-bot]

🟢 Good taste - LGTM

This is textbook deprecation done right:

✅ Backward compatible: RUNTIME_URL still works, just emits a warning
✅ Clear migration path: Warning tells users exactly what to do (OH_WEB_URL)
✅ Reasonable timeline: 5 minor releases (1.14.0 → 1.19.0) gives users runway
✅ Simple implementation: Prefers new env var, falls back to old with warning—no special cases
✅ Comprehensive tests: Covers default, new var, old var with warning, precedence, and explicit override

KEY INSIGHT: Good deprecation eliminates technical debt without breaking user space—this achieves both.

The code is clean, the tests verify real behavior (not just mocks), and the deprecation warning makes the preferred path crystal clear. No complexity, no edge cases, no breaking changes.