Skip to content

πŸ™Œ OpenHands: AI-Driven Development

APP-1197 Consolidate health routes to app_server package (#13724)

Tim O'Farrell0a9570eea22c
diff --git a/openhands/app_server/status/status_router.py b/openhands/app_server/status/status_router.py
new file mode 100644
index 0000000000..0092737d5e
--- /dev/null
+++ b/openhands/app_server/status/status_router.py
@@ -0,0 +1,47 @@
+from fastapi import APIRouter
+
+from openhands.app_server.status.system_stats import get_system_info
+
+router = APIRouter(tags=['Status'])
+
+
+async def alive():
+ """Endpoint for liveness probes.
+
+ If this responds then the server is considered alive.
+ """
+ return {'status': 'ok'}
+
+
+async def health() -> str:
+ """Health check endpoint.
+
+ Returns 'OK' if the service is healthy and ready to accept requests.
+ This is typically used by load balancers and orchestrators (e.g., Kubernetes)
+ to determine if the service should receive traffic.
+ """
+ return 'OK'
+
+
[email protected]('/server_info')
+async def get_server_info():
+ """Server information endpoint.
+
+ Returns system information including CPU count, memory usage, and
+ other runtime details about the server. Useful for monitoring and
+ debugging purposes.
+ """
+ return get_system_info()
+
+
+async def ready() -> str:
+ """Endpoint for readiness probes.
+
+ For now this is functionally the same as the liveness probe, but should
+ we need to establish further invariants in the future, having a separate
+ endpoint will mean we don't need to change client code.
+ """
+ return 'OK'
diff --git a/openhands/runtime/utils/system_stats.py b/openhands/app_server/status/system_stats.py
similarity index 100%
rename from openhands/runtime/utils/system_stats.py
rename to openhands/app_server/status/system_stats.py
diff --git a/openhands/runtime/action_execution_server.py b/openhands/runtime/action_execution_server.py
index 74eed44aa9..afab4abf66 100644
--- a/openhands/runtime/action_execution_server.py
+++ b/openhands/runtime/action_execution_server.py
@@ -40,6 +40,10 @@ from starlette.background import BackgroundTask
from starlette.exceptions import HTTPException as StarletteHTTPException
from uvicorn import run
+from openhands.app_server.status.system_stats import (
+ get_system_stats,
+ update_last_execution_time,
+)
from openhands.core.config.mcp_config import MCPStdioServerConfig
from openhands.core.exceptions import BrowserUnavailableException
from openhands.core.logger import get_uvicorn_json_log_config
@@ -78,10 +82,6 @@ from openhands.runtime.utils.bash import BashSession
from openhands.runtime.utils.files import insert_lines, read_lines
from openhands.runtime.utils.memory_monitor import MemoryMonitor
from openhands.runtime.utils.runtime_init import init_user_and_working_directory
-from openhands.runtime.utils.system_stats import (
- get_system_stats,
- update_last_execution_time,
-)
from openhands.utils.async_utils import call_sync_from_async, wait_all
if sys.platform == 'win32':
diff --git a/openhands/runtime/impl/action_execution/action_execution_client.py b/openhands/runtime/impl/action_execution/action_execution_client.py
index 4598e9e057..9d7765264a 100644
--- a/openhands/runtime/impl/action_execution/action_execution_client.py
+++ b/openhands/runtime/impl/action_execution/action_execution_client.py
@@ -16,6 +16,7 @@ import httpcore
import httpx
from tenacity import retry, retry_if_exception, stop_after_attempt, wait_exponential
+from openhands.app_server.status.system_stats import update_last_execution_time
from openhands.core.config import OpenHandsConfig
from openhands.core.config.mcp_config import (
MCPConfig,
@@ -54,7 +55,6 @@ from openhands.llm.llm_registry import LLMRegistry
from openhands.runtime.base import Runtime
from openhands.runtime.plugins import PluginRequirement
from openhands.runtime.utils.request import send_request
-from openhands.runtime.utils.system_stats import update_last_execution_time
from openhands.utils.http_session import HttpSession
from openhands.utils.tenacity_stop import stop_if_should_exit
diff --git a/openhands/server/app.py b/openhands/server/app.py
index e9f75aa70e..8ecac2b462 100644
--- a/openhands/server/app.py
+++ b/openhands/server/app.py
@@ -25,12 +25,12 @@ from fastapi.responses import JSONResponse
import openhands.agenthub # noqa F401 (we import this to get the agents registered)
from openhands.app_server import v1_router
from openhands.app_server.config import get_app_lifespan_service
+from openhands.app_server.status.status_router import router as health_router
from openhands.integrations.service_types import AuthenticationError
from openhands.server.routes.conversation import app as conversation_api_router
from openhands.server.routes.feedback import app as feedback_api_router
from openhands.server.routes.files import app as files_api_router
from openhands.server.routes.git import app as git_api_router
-from openhands.server.routes.health import add_health_endpoints
from openhands.server.routes.manage_conversations import (
app as manage_conversation_api_router,
)
@@ -101,4 +101,4 @@ if server_config.app_mode == AppMode.OPENHANDS:
if server_config.enable_v1:
app.include_router(v1_router.router)
app.include_router(trajectory_router)
-add_health_endpoints(app)
+app.include_router(health_router)
diff --git a/openhands/server/routes/health.py b/openhands/server/routes/health.py
deleted file mode 100644
index 3bfb57bbdb..0000000000
--- a/openhands/server/routes/health.py
+++ /dev/null
@@ -1,35 +0,0 @@
-# IMPORTANT: LEGACY V0 CODE - Deprecated since version 1.0.0, scheduled for removal April 1, 2026
-# This file is part of the legacy (V0) implementation of OpenHands and will be removed soon as we complete the migration to V1.
-# OpenHands V1 uses the Software Agent SDK for the agentic core and runs a new application server. Please refer to:
-# - V1 agentic core (SDK): https://github.com/OpenHands/software-agent-sdk
-# - V1 application server (in this repo): openhands/app_server/
-# Unless you are working on deprecation, please avoid extending this legacy file and consult the V1 codepaths above.
-# Tag: Legacy-V0
-# This module belongs to the old V0 web server. The V1 application server lives under openhands/app_server/.
-from fastapi import FastAPI
-
-from openhands.runtime.utils.system_stats import get_system_info
-
-
-def add_health_endpoints(app: FastAPI):
- @app.get('/alive')
- async def alive():
- """Endpoint for liveness probes. If this responds then the server is
- considered alive."""
- return {'status': 'ok'}
-
- @app.get('/health')
- async def health() -> str:
- return 'OK'
-
- @app.get('/server_info')
- async def get_server_info():
- return get_system_info()
-
- @app.get('/ready')
- async def ready() -> str:
- """Endpoint for readiness probes. For now this is functionally the same as
- the liveness probe, but should be need to establish further invariants in
- the future, having a separate endpoint will mean we don't need to change
- client code."""
- return 'OK'
diff --git a/tests/runtime/utils/test_system_stats.py b/tests/runtime/utils/test_system_stats.py
index 7fd52cb221..c190698525 100644
--- a/tests/runtime/utils/test_system_stats.py
+++ b/tests/runtime/utils/test_system_stats.py
@@ -5,7 +5,7 @@ from unittest.mock import patch
import psutil
-from openhands.runtime.utils.system_stats import (
+from openhands.app_server.status.system_stats import (
get_system_info,
get_system_stats,
update_last_execution_time,
@@ -146,12 +146,12 @@ def test_idle_time_calculation(mock_time):
# Import the module again to reset the global variables with our mocked time
import importlib
- import openhands.runtime.utils.system_stats
+ import openhands.app_server.status.system_stats
- importlib.reload(openhands.runtime.utils.system_stats)
+ importlib.reload(openhands.app_server.status.system_stats)
# Get system info
- from openhands.runtime.utils.system_stats import get_system_info
+ from openhands.app_server.status.system_stats import get_system_info
info = get_system_info()
diff --git a/tests/unit/app_server/test_status_router.py b/tests/unit/app_server/test_status_router.py
new file mode 100644
index 0000000000..96bcfa653b
--- /dev/null
+++ b/tests/unit/app_server/test_status_router.py
@@ -0,0 +1,84 @@
+"""Unit tests for the status router endpoints.
+
+This module tests the status router endpoints (/alive, /health, /server_info, /ready).
+"""
+
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from openhands.app_server.status.status_router import router
+
+
+def test_client():
+ """Create a test client with the status router.
+
+ This fixture sets up a FastAPI test client with the status router included.
+ No authentication is required for these endpoints.
+ """
+ app = FastAPI()
+ app.include_router(router)
+ client = TestClient(app)
+ yield client
+
+
+class TestAliveEndpoint:
+ """Test suite for the /alive endpoint."""
+
+ def test_alive_returns_ok_status(self, test_client):
+ """Test that /alive returns status: ok."""
+ response = test_client.get('/alive')
+
+ assert response.status_code == 200
+ assert response.json() == {'status': 'ok'}
+
+
+class TestHealthEndpoint:
+ """Test suite for the /health endpoint."""
+
+ def test_health_returns_ok(self, test_client):
+ """Test that /health returns 'OK' string."""
+ response = test_client.get('/health')
+
+ assert response.status_code == 200
+ # FastAPI returns JSON-encoded string, so response.json() gives 'OK'
+ assert response.json() == 'OK'
+
+
+class TestServerInfoEndpoint:
+ """Test suite for the /server_info endpoint."""
+
+ def test_server_info_returns_system_info(self, test_client):
+ """Test that /server_info returns system information."""
+ response = test_client.get('/server_info')
+
+ assert response.status_code == 200
+ # Should return a dict with system info
+ assert isinstance(response.json(), dict)
+
+
+class TestReadyEndpoint:
+ """Test suite for the /ready endpoint."""
+
+ def test_ready_returns_ok(self, test_client):
+ """Test that /ready returns 'OK' string."""
+ response = test_client.get('/ready')
+
+ assert response.status_code == 200
+ # FastAPI returns JSON-encoded string, so response.json() gives 'OK'
+ assert response.json() == 'OK'
+
+
+class TestAllStatusEndpoints:
+ """Integration tests for all status endpoints."""
+
+ def test_all_endpoints_accessible(self, test_client):
+ """Test that all status endpoints are accessible and return 200."""
+ endpoints = ['/alive', '/health', '/server_info', '/ready']
+
+ for endpoint in endpoints:
+ response = test_client.get(endpoint)
+ assert response.status_code == 200, (
+ f'Endpoint {endpoint} returned {response.status_code}'
+ )