Fix HF Space web UI gateway port handoff

docker/entrypoint.sh

@@ -102,10 +102,11 @@ if [ $# -eq 0 ] && [ -n "${SPACE_ID:-}${SPACE_HOST:-}" ]; then
     export HERMES_BIN
 
     export API_SERVER_ENABLED="${API_SERVER_ENABLED:-true}"
-    export API_SERVER_HOST="${API_SERVER_HOST:-127.0.0.1}"
-    export API_SERVER_PORT="${API_SERVER_PORT:-8642}"
     export PORT="${PORT:-7860}"
-    export UPSTREAM="${UPSTREAM:-http://127.0.0.1:${API_SERVER_PORT}}"
+    # Let hermes-web-ui's GatewayManager own port selection via config.yaml.
+    # Exporting a default API_SERVER_PORT here forces child gateway processes
+    # back onto 8642, which breaks health checks when the UI assigns 8643+.
+    export UPSTREAM="${UPSTREAM:-$(python3 "$RUNTIME_HELPER" api-server-upstream)}"
     export AUTH_DISABLED="${AUTH_DISABLED:-false}"
     export AUTH_TOKEN="${AUTH_TOKEN:-wangjx0515}"
 

docker/space_runtime.py

@@ -6,10 +6,19 @@ import os
 import shlex
 import sys
 from collections.abc import Mapping, Sequence
+from pathlib import Path
 
 SPACE_WEB_ARGS = ["dashboard", "--host", "0.0.0.0", "--port", "7860", "--no-open"]
 DEFAULT_HERMES_HOME = "/opt/data"
 SPACE_HERMES_HOME = "/data/hermes"
+DEFAULT_API_SERVER_PORT = "8642"
+DEFAULT_API_SERVER_UPSTREAM_HOST = "127.0.0.1"
+API_SERVER_PORT_PATHS = (
+    ("platforms", "api_server", "extra", "port"),
+    ("platforms", "api_server", "port"),
+    ("api_server", "extra", "port"),
+    ("api_server", "port"),
+)
 
 
 def is_hf_space(env: Mapping[str, str]) -> bool:
@@ -39,6 +48,94 @@ def resolve_hermes_command(
     return [executable, *resolve_default_command(env, argv)]
 
 
+def _resolve_config_path(env: Mapping[str, str]) -> Path:
+    return Path(resolve_hermes_home(env)) / "config.yaml"
+
+
+def _strip_inline_comment(text: str) -> str:
+    quote: str | None = None
+    result: list[str] = []
+    for char in text:
+        if char in {"'", '"'}:
+            if quote == char:
+                quote = None
+            elif quote is None:
+                quote = char
+        if char == "#" and quote is None:
+            break
+        result.append(char)
+    return "".join(result).rstrip()
+
+
+def _parse_scalar(text: str) -> str | None:
+    value = _strip_inline_comment(text).strip()
+    if not value:
+        return None
+    if len(value) >= 2 and value[0] == value[-1] and value[0] in {"'", '"'}:
+        return value[1:-1]
+    return value
+
+
+def _read_yaml_path_value(text: str, target_paths: Sequence[tuple[str, ...]]) -> str | None:
+    stack: list[tuple[int, str]] = []
+    for raw_line in text.splitlines():
+        line = raw_line.rstrip()
+        stripped = line.lstrip(" ")
+        if not stripped or stripped.startswith("#") or stripped.startswith("-"):
+            continue
+
+        indent = len(line) - len(stripped)
+        key, separator, remainder = stripped.partition(":")
+        if not separator:
+            continue
+
+        while stack and indent <= stack[-1][0]:
+            stack.pop()
+
+        path = tuple(part for _, part in stack) + (key.strip(),)
+        value = _parse_scalar(remainder)
+        if path in target_paths and value is not None:
+            return value
+        if value is None:
+            stack.append((indent, key.strip()))
+
+    return None
+
+
+def _config_api_server_port(env: Mapping[str, str]) -> str | None:
+    config_path = _resolve_config_path(env)
+    try:
+        config_text = config_path.read_text(encoding="utf-8")
+    except OSError:
+        return None
+
+    value = _read_yaml_path_value(config_text, API_SERVER_PORT_PATHS)
+    if value is None:
+        return None
+
+    try:
+        port = int(value, 10)
+    except ValueError:
+        return None
+    if 0 < port <= 65535:
+        return str(port)
+    return None
+
+
+def resolve_api_server_port(env: Mapping[str, str]) -> str:
+    explicit = (env.get("API_SERVER_PORT") or "").strip()
+    if explicit:
+        return explicit
+    return _config_api_server_port(env) or DEFAULT_API_SERVER_PORT
+
+
+def resolve_api_server_upstream(env: Mapping[str, str]) -> str:
+    explicit = (env.get("UPSTREAM") or "").strip()
+    if explicit:
+        return explicit
+    return f"http://{DEFAULT_API_SERVER_UPSTREAM_HOST}:{resolve_api_server_port(env)}"
+
+
 def _command_string(env: Mapping[str, str], argv: Sequence[str]) -> str:
     executable = env.get("HERMES_EXECUTABLE", "hermes")
     return shlex.join(resolve_hermes_command(env, argv, executable=executable))
@@ -56,6 +153,14 @@ def main(argv: Sequence[str] | None = None) -> int:
         print(_command_string(env, argv[1:]))
         return 0
 
+    if argv[0] == "api-server-port":
+        print(resolve_api_server_port(env))
+        return 0
+
+    if argv[0] == "api-server-upstream":
+        print(resolve_api_server_upstream(env))
+        return 0
+
     if argv[0] == "exec":
         print_only = False
         args = argv[1:]
@@ -73,7 +178,9 @@ def main(argv: Sequence[str] | None = None) -> int:
         os.execvpe(command[0], command, dict(env))
 
     prog = os.path.basename(sys.argv[0] or "space_runtime.py")
-    raise SystemExit(f"Usage: {prog} [home|command|exec [--print-only] [args...]]")
+    raise SystemExit(
+        f"Usage: {prog} [home|command|api-server-port|api-server-upstream|exec [--print-only] [args...]]"
+    )
 
 
 if __name__ == "__main__":

tests/hermes_cli/test_space_runtime.py

@@ -1,6 +1,8 @@
 from pathlib import Path
 
 from docker.space_runtime import (
+    resolve_api_server_port,
+    resolve_api_server_upstream,
     resolve_default_command,
     resolve_hermes_command,
     resolve_hermes_home,
@@ -12,7 +14,7 @@ def test_space_runtime_uses_dashboard_defaults():
 
     assert resolve_hermes_home(env) == "/data/hermes"
     assert resolve_default_command(env, []) == [
-        "web",
+        "dashboard",
         "--host",
         "0.0.0.0",
         "--port",
@@ -38,7 +40,7 @@ def test_space_runtime_builds_hermes_command():
 
     assert resolve_hermes_command(env, [], executable="hermes") == [
         "hermes",
-        "web",
+        "dashboard",
         "--host",
         "0.0.0.0",
         "--port",
@@ -51,6 +53,43 @@ def test_non_space_runtime_defaults_to_cli_command():
     assert resolve_hermes_command({}, [], executable="hermes") == ["hermes"]
 
 
+def test_space_runtime_reads_api_server_port_from_config(tmp_path):
+    config_path = tmp_path / "config.yaml"
+    config_path.write_text(
+        "platforms:\n"
+        "  api_server:\n"
+        "    extra:\n"
+        "      port: 8643\n",
+        encoding="utf-8",
+    )
+
+    env = {"SPACE_ID": "cjovs/HermesAgent", "HERMES_HOME": str(tmp_path)}
+
+    assert resolve_api_server_port(env) == "8643"
+    assert resolve_api_server_upstream(env) == "http://127.0.0.1:8643"
+
+
+def test_space_runtime_preserves_explicit_api_server_overrides(tmp_path):
+    config_path = tmp_path / "config.yaml"
+    config_path.write_text(
+        "platforms:\n"
+        "  api_server:\n"
+        "    extra:\n"
+        "      port: 8643\n",
+        encoding="utf-8",
+    )
+
+    env = {
+        "SPACE_ID": "cjovs/HermesAgent",
+        "HERMES_HOME": str(tmp_path),
+        "API_SERVER_PORT": "9999",
+        "UPSTREAM": "http://127.0.0.1:9998",
+    }
+
+    assert resolve_api_server_port(env) == "9999"
+    assert resolve_api_server_upstream(env) == "http://127.0.0.1:9998"
+
+
 def test_readme_declares_docker_space_metadata():
     readme = Path("README.md").read_text(encoding="utf-8")
 

tests/hermes_cli/test_space_web_ui_runtime_requirements.py

@@ -28,3 +28,9 @@ def test_space_entrypoint_marks_hf_space_as_container_for_web_ui():
 
     assert 'touch "/.dockerenv"' in entrypoint
     assert "SPACE_ID" in entrypoint or "SPACE_HOST" in entrypoint
+
+
+def test_space_entrypoint_does_not_force_api_server_port_defaults():
+    entrypoint = Path("docker/entrypoint.sh").read_text(encoding="utf-8")
+
+    assert 'export API_SERVER_PORT="${API_SERVER_PORT:-8642}"' not in entrypoint