feat: add /ready endpoint for proper Kubernetes readiness checks

[neubig]

Problem

The existing /alive and /health endpoints return 200 immediately when the server process starts, but the server may still be initializing services (VSCode, desktop, tool preload, etc.).

This causes issues where Kubernetes marks pods as "ready" before the application is actually ready to serve requests, leading to:

• 503 errors during initial startup
• 503 errors during container restarts (while new container initializes)

Solution

Add a /ready endpoint that returns:

• 503 Service Unavailable during initialization
• 200 OK after all services have finished initializing

This follows the Kubernetes best practice of separating:

• Liveness probes (/alive, /health) - Is the process running?
• Readiness probes (/ready) - Is the server ready to receive traffic?

Changes

server_details_router.py

• Add _initialization_complete flag (default False)
• Add mark_initialization_complete() function to set the flag
• Add is_ready() function to check the flag
• Add /ready endpoint that checks initialization status

api.py

• Import mark_initialization_complete
• Call it after all async initialization tasks complete

Usage

This endpoint should be used by Kubernetes readiness probes:

readinessProbe:
  httpGet:
    path: /ready
    port: 60000
  initialDelaySeconds: 5
  periodSeconds: 5
  failureThreshold: 3

Related PRs

• https://github.com/OpenHands/runtime-api/pull/382 - Adds readiness probe configuration to use this endpoint

---

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.12-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:bfc0125-python

Run

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

All tags pushed for this build

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

About Multi-Architecture Support

• Each variant tag (e.g., bfc0125-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., bfc0125-python-amd64) are also available if needed

[openhands-ai]

Looks like there are a few issues preventing this PR from being merged!

• GitHub Actions are failing:
  • Pre-commit checks

If you'd like me to help, just leave a comment, like

@OpenHands please fix the failing actions on PR #1810 at branch `fix-readiness-endpoint`

Feel free to include any additional details that might help me get this PR into a better state.

_{^{You can manage your notification settings}}

[all-hands-bot]

This PR adds a useful /ready endpoint for Kubernetes readiness checks, but there is a critical bug where the server marks itself as ready even if service initialization fails. See inline comments for details.

[neubig]

@OpenHands see the all-hands-bot review comments, and my responses to them. Fix according to the directions in my responses.

[openhands-ai]

I'm on it! neubig can track my progress at all-hands.dev

[openhands-ai]

I've addressed all the review comments from all-hands-bot according to neubig's directions. Here's a summary:

Changes Made (already pushed to fix-readiness-endpoint)

1. ✅ Fixed critical bug in api.py (neubig said: "Fix")

• Now captures results from asyncio.gather() and checks for exceptions before calling mark_initialization_complete()
• If any exceptions occurred during service initialization, the server remains in "initializing" state and logs the errors
• This prevents the server from being marked as ready when initialization actually failed

2. ✅ Removed unused is_ready() function from server_details_router.py (neubig said: "Fix")

• Removed the dead code that was never used

3. ✅ Created issue #1825 for asyncio.Event() suggestion (neubig said: "don't fix here but open an issue. Label it as 'good-first-issue'")

• Consider using asyncio.Event() for thread-safe initialization state #1825
• Labeled with "good first issue" and "enhancement"

4. ✅ Created issue #1826 for response format inconsistency (neubig said: "Don't fix in this PR, but open an issue")

• Standardize response format across health check endpoints #1826
• Labeled with "enhancement"

5. ❌ No action needed for async def suggestion (neubig said: "Deeming unnecessary for now, closing")

All pre-commit checks pass and changes have been pushed to the PR branch.

View full conversation

[all-hands-bot]

The implementation looks solid and follows Kubernetes best practices for separating liveness and readiness probes. Just a couple minor type hint suggestions for consistency.

[all-hands-bot]

[Automatic Post]: This PR seems to be currently waiting for review. @tofarr @simonrosenberg, could you please take a look when you have a chance?

[tofarr]

I think we should also deprecate the existing methods given that they do not perform correctly