openhands-agent-server 1.8.2__py3-none-any.whl

openhands/agent_server/dependencies.py

@@ -0,0 +1,72 @@
+from uuid import UUID
+
+from fastapi import Depends, HTTPException, Query, Request, status
+from fastapi.security import APIKeyHeader
+
+from openhands.agent_server.config import Config
+from openhands.agent_server.conversation_service import ConversationService
+from openhands.agent_server.event_service import EventService
+
+
+_SESSION_API_KEY_HEADER = APIKeyHeader(name="X-Session-API-Key", auto_error=False)
+
+
+def create_session_api_key_dependency(config: Config):
+    """Create a session API key dependency with the given config."""
+
+    def check_session_api_key(
+        session_api_key: str | None = Depends(_SESSION_API_KEY_HEADER),
+    ):
+        """Check the session API key and throw an exception if incorrect. Having this as
+        a dependency means it appears in OpenAPI Docs
+        """
+        if config.session_api_keys and session_api_key not in config.session_api_keys:
+            raise HTTPException(status.HTTP_401_UNAUTHORIZED)
+
+    return check_session_api_key
+
+
+def create_websocket_session_api_key_dependency(config: Config):
+    """Create a WebSocket session API key dependency with the given config.
+
+    WebSocket connections cannot send custom headers directly from browsers,
+    so we use query parameters instead.
+    """
+
+    def check_websocket_session_api_key(
+        session_api_key: str | None = Query(None, alias="session_api_key"),
+    ):
+        """Check the session API key from query parameter for WebSocket connections."""
+        if config.session_api_keys and session_api_key not in config.session_api_keys:
+            raise HTTPException(status.HTTP_401_UNAUTHORIZED)
+
+    return check_websocket_session_api_key
+
+
+def get_conversation_service(request: Request):
+    """Get the conversation service from app state.
+
+    This dependency ensures that the conversation service is properly initialized
+    through the application lifespan context manager.
+    """
+
+    service = getattr(request.app.state, "conversation_service", None)
+    if service is None:
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Conversation service is not available",
+        )
+    return service
+
+
+async def get_event_service(
+    conversation_id: UUID,
+    conversation_service: ConversationService = Depends(get_conversation_service),
+) -> EventService:
+    event_service = await conversation_service.get_event_service(conversation_id)
+    if event_service is None:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Conversation not found: {conversation_id}",
+        )
+    return event_service

openhands/agent_server/desktop_router.py

@@ -0,0 +1,47 @@
+"""Desktop router for agent server API endpoints."""
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+from openhands.agent_server.desktop_service import get_desktop_service
+from openhands.sdk.logger import get_logger
+
+
+logger = get_logger(__name__)
+
+desktop_router = APIRouter(prefix="/desktop", tags=["Desktop"])
+
+
+class DesktopUrlResponse(BaseModel):
+    """Response model for Desktop URL."""
+
+    url: str | None
+
+
+@desktop_router.get("/url", response_model=DesktopUrlResponse)
+async def get_desktop_url(
+    base_url: str = "http://localhost:8002",
+) -> DesktopUrlResponse:
+    """Get the noVNC URL for desktop access.
+
+    Args:
+        base_url: Base URL for the noVNC server (default: http://localhost:8002)
+
+    Returns:
+        noVNC URL if available, None otherwise
+    """
+    desktop_service = get_desktop_service()
+    if desktop_service is None:
+        raise HTTPException(
+            status_code=503,
+            detail=(
+                "Desktop is disabled in configuration. Set enable_vnc=true to enable."
+            ),
+        )
+
+    try:
+        url = desktop_service.get_vnc_url(base_url)
+        return DesktopUrlResponse(url=url)
+    except Exception as e:
+        logger.error(f"Error getting desktop URL: {e}")
+        raise HTTPException(status_code=500, detail="Failed to get desktop URL")

openhands/agent_server/desktop_service.py

@@ -0,0 +1,212 @@
+"""Desktop service for launching VNC desktop via desktop_launch.sh script."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import subprocess
+from pathlib import Path
+
+from openhands.agent_server.config import get_default_config
+from openhands.sdk.logger import get_logger
+
+
+logger = get_logger(__name__)
+
+
+class DesktopService:
+    """Simple desktop service that launches desktop_launch.sh script."""
+
+    def __init__(self):
+        self._proc: asyncio.subprocess.Process | None = None
+        self.novnc_port: int = int(os.getenv("NOVNC_PORT", "8002"))
+
+    async def start(self) -> bool:
+        """Start the VNC desktop stack."""
+        if self.is_running():
+            logger.info("Desktop already running")
+            return True
+
+        # --- Env defaults (match bash behavior) ---
+        env = os.environ.copy()
+        display = env.get("DISPLAY", ":1")
+        user = env.get("USER") or env.get("USERNAME") or "openhands"
+        home = Path(env.get("HOME") or f"/home/{user}")
+        vnc_geometry = env.get("VNC_GEOMETRY", "1280x800")
+        novnc_proxy = Path("/usr/share/novnc/utils/novnc_proxy")
+        novnc_web = Path(env.get("NOVNC_WEB", "/opt/novnc-web"))
+
+        # --- Dirs & ownership (idempotent) ---
+        try:
+            for p in (home / ".vnc", home / ".config", home / "Downloads"):
+                p.mkdir(parents=True, exist_ok=True)
+        except Exception as e:
+            logger.error("Failed preparing directories/ownership: %s", e)
+            return False
+
+        # --- xstartup for XFCE (create once) ---
+        xstartup = home / ".vnc" / "xstartup"
+        if not xstartup.exists():
+            try:
+                xstartup.write_text(
+                    "#!/bin/sh\n"
+                    "unset SESSION_MANAGER\n"
+                    "unset DBUS_SESSION_BUS_ADDRESS\n"
+                    "exec startxfce4\n"
+                )
+                xstartup.chmod(0o755)
+            except Exception as e:
+                logger.error("Failed writing xstartup: %s", e)
+                return False
+
+        # --- Start TigerVNC if not running (bind to loopback; novnc proxies) ---
+        try:
+            # Roughly equivalent to: pgrep -f "Xvnc .*:1"
+            xvnc_running = (
+                subprocess.run(
+                    ["pgrep", "-f", f"Xvnc .*{display}"],
+                    capture_output=True,
+                    text=True,
+                    timeout=3,
+                ).returncode
+                == 0
+            )
+        except Exception:
+            xvnc_running = False
+
+        if not xvnc_running:
+            logger.info("Starting TigerVNC on %s (%s)...", display, vnc_geometry)
+            # vncserver <DISPLAY> -geometry <geom> -depth 24 -localhost yes
+            rc = subprocess.run(
+                [
+                    "vncserver",
+                    display,
+                    "-geometry",
+                    vnc_geometry,
+                    "-depth",
+                    "24",
+                    "-localhost",
+                    "yes",
+                    "-SecurityTypes",
+                    "None",
+                ],
+                env=env,
+            ).returncode
+            if rc != 0:
+                logger.error("vncserver failed with rc=%s", rc)
+                return False
+
+        # --- Start noVNC proxy (as our foreground/managed process) ---
+        # Equivalent to: pgrep -f "[n]ovnc_proxy .*--listen .*<port>"
+        try:
+            novnc_running = (
+                subprocess.run(
+                    ["pgrep", "-f", rf"novnc_proxy .*--listen .*{self.novnc_port}"],
+                    capture_output=True,
+                    text=True,
+                    timeout=3,
+                ).returncode
+                == 0
+            )
+        except Exception:
+            novnc_running = False
+
+        if novnc_running:
+            logger.info("noVNC already running on port %d", self.novnc_port)
+            self._proc = None  # we didn't start it; don't own its lifecycle
+        else:
+            if not novnc_proxy.exists():
+                logger.error("noVNC proxy not found at %s", novnc_proxy)
+                return False
+            logger.info(
+                "Starting noVNC proxy on 0.0.0.0:%d -> 127.0.0.1:5901 ...",
+                self.novnc_port,
+            )
+            try:
+                # Store this as the managed long-running process
+                self._proc = await asyncio.create_subprocess_exec(
+                    str(novnc_proxy),
+                    "--listen",
+                    f"0.0.0.0:{self.novnc_port}",
+                    "--vnc",
+                    "127.0.0.1:5901",
+                    "--web",
+                    str(novnc_web),
+                    stdout=asyncio.subprocess.PIPE,
+                    stderr=asyncio.subprocess.STDOUT,
+                    env=env,
+                )
+            except Exception as e:
+                logger.error("Failed to start noVNC proxy: %s", e)
+                return False
+
+        logger.info(
+            "noVNC URL: http://localhost:%d/vnc.html?autoconnect=1&resize=remote",
+            self.novnc_port,
+        )
+
+        # Small grace period so callers relying on your old sleep(2) don't break
+        await asyncio.sleep(2)
+
+        # Final sanity: either our managed noVNC is alive or Xvnc is alive
+        if (self._proc and self._proc.returncode is None) or self.is_running():
+            logger.info("Desktop started successfully")
+            return True
+
+        logger.error("Desktop failed to start (noVNC/Xvnc not healthy)")
+        return False
+
+    async def stop(self) -> None:
+        """Stop the desktop process."""
+        if self._proc and self._proc.returncode is None:
+            try:
+                self._proc.terminate()
+                await asyncio.wait_for(self._proc.wait(), timeout=5)
+                logger.info("Desktop stopped")
+            except TimeoutError:
+                logger.warning("Desktop did not stop gracefully, killing process")
+                self._proc.kill()
+                await self._proc.wait()
+            except Exception as e:
+                logger.error("Error stopping desktop: %s", e)
+            finally:
+                self._proc = None
+
+    def is_running(self) -> bool:
+        """Check if desktop is running."""
+        if self._proc and self._proc.returncode is None:
+            return True
+
+        # Check if VNC server is running
+        try:
+            result = subprocess.run(
+                ["pgrep", "-f", "Xvnc"], capture_output=True, text=True, timeout=3
+            )
+            return result.returncode == 0
+        except Exception:
+            return False
+
+    def get_vnc_url(self, base: str = "http://localhost:8003") -> str | None:
+        """Get the noVNC URL for desktop access."""
+        if not self.is_running():
+            return None
+        return f"{base}/vnc.html?autoconnect=1&resize=remote"
+
+
+# ------- module-level accessor -------
+
+_desktop_service: DesktopService | None = None
+
+
+def get_desktop_service() -> DesktopService | None:
+    """Get the desktop service instance if VNC is enabled."""
+    global _desktop_service
+    config = get_default_config()
+
+    if not config.enable_vnc:
+        logger.info("VNC desktop is disabled in configuration")
+        return None
+
+    if _desktop_service is None:
+        _desktop_service = DesktopService()
+    return _desktop_service

openhands/agent_server/docker/Dockerfile

@@ -0,0 +1,244 @@
+# syntax=docker/dockerfile:1.7
+
+ARG BASE_IMAGE=nikolaik/python-nodejs:python3.12-nodejs22
+ARG USERNAME=openhands
+ARG UID=10001
+ARG GID=10001
+ARG PORT=8000
+
+####################################################################################
+# Builder (source mode)
+# We copy source + build a venv here for local dev and debugging.
+####################################################################################
+FROM python:3.12-bullseye AS builder
+ARG USERNAME UID GID
+ENV UV_PROJECT_ENVIRONMENT=/agent-server/.venv
+ENV UV_PYTHON_INSTALL_DIR=/agent-server/uv-managed-python
+
+COPY --from=ghcr.io/astral-sh/uv /uv /uvx /bin/
+
+RUN groupadd -g ${GID} ${USERNAME} \
+ && useradd -m -u ${UID} -g ${GID} -s /usr/sbin/nologin ${USERNAME}
+USER ${USERNAME}
+WORKDIR /agent-server
+# Cache-friendly: lockfiles first
+COPY --chown=${USERNAME}:${USERNAME} pyproject.toml uv.lock README.md LICENSE ./
+COPY --chown=${USERNAME}:${USERNAME} openhands-sdk ./openhands-sdk
+COPY --chown=${USERNAME}:${USERNAME} openhands-tools ./openhands-tools
+COPY --chown=${USERNAME}:${USERNAME} openhands-workspace ./openhands-workspace
+COPY --chown=${USERNAME}:${USERNAME} openhands-agent-server ./openhands-agent-server
+RUN --mount=type=cache,target=/home/${USERNAME}/.cache,uid=${UID},gid=${GID} \
+    uv python install 3.12 && uv venv --python 3.12 .venv && uv sync --frozen --no-editable --managed-python
+
+####################################################################################
+# Binary Builder (binary mode)
+# We run pyinstaller here to produce openhands-agent-server
+####################################################################################
+FROM builder AS binary-builder
+ARG USERNAME UID GID
+
+# We need --dev for pyinstaller
+RUN --mount=type=cache,target=/home/${USERNAME}/.cache,uid=${UID},gid=${GID} \
+    uv sync --frozen --dev --no-editable
+
+RUN --mount=type=cache,target=/home/${USERNAME}/.cache,uid=${UID},gid=${GID} \
+    uv run pyinstaller openhands-agent-server/openhands/agent_server/agent-server.spec
+# Fail fast if the expected binary is missing
+RUN test -x /agent-server/dist/openhands-agent-server
+
+####################################################################################
+# Base image (minimal)
+# It includes only basic packages and the UV runtime.
+# No Docker, no VNC, no Desktop, no VSCode Web.
+# Suitable for running in headless/evaluation mode.
+####################################################################################
+FROM ${BASE_IMAGE} AS base-image-minimal
+ARG USERNAME UID GID PORT
+
+# Install base packages and create user
+RUN set -eux; \
+    # Install base packages (works for both Debian-based images)
+    apt-get update; \
+    apt-get install -y --no-install-recommends \
+        ca-certificates curl wget sudo apt-utils git jq tmux build-essential \
+        coreutils util-linux procps findutils grep sed \
+        # Docker dependencies
+        apt-transport-https gnupg lsb-release; \
+    \
+    # Create user and group
+    (getent group ${GID} || groupadd -g ${GID} ${USERNAME}); \
+    (id -u ${USERNAME} >/dev/null 2>&1 || useradd -m -u ${UID} -g ${GID} -s /bin/bash ${USERNAME}); \
+    # Add user to sudo group
+    usermod -aG sudo ${USERNAME}; \
+    echo "${USERNAME} ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers; \
+    # Create workspace directory
+    mkdir -p /workspace/project; \
+    chown -R ${USERNAME}:${USERNAME} /workspace; \
+    rm -rf /var/lib/apt/lists/*
+
+# NOTE: we should NOT include UV_PROJECT_ENVIRONMENT here, 
+# since the agent might use it to perform other work (e.g. tools that use Python)
+COPY --from=ghcr.io/astral-sh/uv /uv /uvx /bin/
+
+USER ${USERNAME}
+WORKDIR /
+ENV OH_ENABLE_VNC=false
+ENV LOG_JSON=true
+EXPOSE ${PORT}
+
+####################################################################################
+# Base image (full)
+# It includes additional Docker, VNC, Desktop, and VSCode Web.
+####################################################################################
+FROM base-image-minimal AS base-image
+ARG USERNAME
+
+USER root
+# --- VSCode Web ---
+ENV EDITOR=code \
+    VISUAL=code \
+    GIT_EDITOR="code --wait" \
+    OPENVSCODE_SERVER_ROOT=/openhands/.openvscode-server
+ARG RELEASE_TAG="openvscode-server-v1.98.2"
+ARG RELEASE_ORG="gitpod-io"
+RUN set -eux; \
+    # Create necessary directories
+    mkdir -p $(dirname ${OPENVSCODE_SERVER_ROOT}); \
+    \
+    # Determine architecture
+    arch=$(uname -m); \
+    if [ "${arch}" = "x86_64" ]; then \
+        arch="x64"; \
+    elif [ "${arch}" = "aarch64" ]; then \
+        arch="arm64"; \
+    elif [ "${arch}" = "armv7l" ]; then \
+        arch="armhf"; \
+    fi; \
+    \
+    # Download and install VSCode Server
+    wget https://github.com/${RELEASE_ORG}/openvscode-server/releases/download/${RELEASE_TAG}/${RELEASE_TAG}-linux-${arch}.tar.gz; \
+    tar -xzf ${RELEASE_TAG}-linux-${arch}.tar.gz; \
+    if [ -d "${OPENVSCODE_SERVER_ROOT}" ]; then rm -rf "${OPENVSCODE_SERVER_ROOT}"; fi; \
+    mv ${RELEASE_TAG}-linux-${arch} ${OPENVSCODE_SERVER_ROOT}; \
+    cp ${OPENVSCODE_SERVER_ROOT}/bin/remote-cli/openvscode-server ${OPENVSCODE_SERVER_ROOT}/bin/remote-cli/code; \
+    rm -f ${RELEASE_TAG}-linux-${arch}.tar.gz; \
+    \
+    # Set proper ownership
+    chown -R ${USERNAME}:${USERNAME} ${OPENVSCODE_SERVER_ROOT}
+
+
+# Include VSCode extensions alongside the server so targets inheriting base-image
+# implicitly get the extensions; minimal images (without VSCode) won't.
+COPY --chown=${USERNAME}:${USERNAME} --from=builder /agent-server/openhands-agent-server/openhands/agent_server/vscode_extensions ${OPENVSCODE_SERVER_ROOT}/extensions
+
+# --- Docker ---
+RUN set -eux; \
+    # Determine OS type and install Docker accordingly
+    if grep -q "ubuntu" /etc/os-release; then \
+        # Handle Ubuntu
+        install -m 0755 -d /etc/apt/keyrings; \
+        curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc; \
+        chmod a+r /etc/apt/keyrings/docker.asc; \
+        echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null; \
+    else \
+        # Handle Debian
+        install -m 0755 -d /etc/apt/keyrings; \
+        curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc; \
+        chmod a+r /etc/apt/keyrings/docker.asc; \
+        echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian bookworm stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null; \
+    fi; \
+    # Install Docker Engine, containerd, and Docker Compose
+    apt-get update; \
+    apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin; \
+    apt-get clean; \
+    rm -rf /var/lib/apt/lists/*
+
+# Configure Docker daemon with MTU 1450 to prevent packet fragmentation issues
+RUN mkdir -p /etc/docker && \
+    echo '{"mtu": 1450}' > /etc/docker/daemon.json
+
+# --- GitHub CLI ---
+RUN set -eux; \
+    mkdir -p -m 755 /etc/apt/keyrings; \
+    wget -nv -O /etc/apt/keyrings/githubcli-archive-keyring.gpg \
+        https://cli.github.com/packages/githubcli-archive-keyring.gpg; \
+    chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg; \
+    echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
+        > /etc/apt/sources.list.d/github-cli.list; \
+    apt-get update; \
+    apt-get install -y gh; \
+    apt-get clean; \
+    rm -rf /var/lib/apt/lists/*
+
+# --- VNC + Desktop + noVNC ---
+RUN set -eux; \
+  apt-get update; \
+  apt-get install -y --no-install-recommends \
+    # GUI bits (remove entirely if headless)
+    tigervnc-standalone-server xfce4 dbus-x11 novnc websockify \
+    # Browser
+    $(if grep -q "ubuntu" /etc/os-release; then echo "chromium-browser"; else echo "chromium"; fi); \
+  apt-get clean; rm -rf /var/lib/apt/lists/*
+
+ENV NOVNC_WEB=/usr/share/novnc \
+    NOVNC_PORT=8002 \
+    DISPLAY=:1 \
+    VNC_GEOMETRY=1280x800 \
+    CHROME_BIN=/usr/bin/chromium \
+    PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium \
+    CHROMIUM_FLAGS="--no-sandbox --disable-dev-shm-usage --disable-gpu"
+
+RUN chown -R ${USERNAME}:${USERNAME} ${NOVNC_WEB}
+# Override default XFCE wallpaper
+COPY --chown=${USERNAME}:${USERNAME} openhands-agent-server/openhands/agent_server/docker/wallpaper.svg /usr/share/backgrounds/xfce/xfce-shapes.svg
+
+USER ${USERNAME}
+WORKDIR /
+ENV OH_ENABLE_VNC=false
+ENV LOG_JSON=true
+EXPOSE ${PORT} ${NOVNC_PORT}
+
+
+####################################################################################
+####################################################################################
+# Build Targets
+####################################################################################
+####################################################################################
+
+############################
+# Target A: source
+# Local dev and debugging mode: copy source + venv from builder
+############################
+FROM base-image AS source
+ARG USERNAME
+ENV UV_PYTHON_INSTALL_DIR=/agent-server/uv-managed-python
+COPY --chown=${USERNAME}:${USERNAME} --from=builder /agent-server /agent-server
+ENTRYPOINT ["/agent-server/.venv/bin/python", "-m", "openhands.agent_server"]
+
+FROM base-image-minimal AS source-minimal
+ARG USERNAME
+ENV UV_PYTHON_INSTALL_DIR=/agent-server/uv-managed-python
+COPY --chown=${USERNAME}:${USERNAME} --from=builder /agent-server /agent-server
+ENTRYPOINT ["/agent-server/.venv/bin/python", "-m", "openhands.agent_server"]
+
+############################
+# Target B: binary-runtime
+# Production mode: build the binary inside Docker and copy it in.
+# NOTE: no support for external artifact contexts anymore.
+############################
+FROM base-image AS binary
+ARG USERNAME
+
+COPY --chown=${USERNAME}:${USERNAME} --from=binary-builder /agent-server/dist/openhands-agent-server /usr/local/bin/openhands-agent-server
+RUN chmod +x /usr/local/bin/openhands-agent-server
+# Fix library path to use system GCC libraries instead of bundled ones
+ENV LD_LIBRARY_PATH=/usr/lib/aarch64-linux-gnu:/usr/lib:/usr/lib/x86_64-linux-gnu:$LD_LIBRARY_PATH
+ENTRYPOINT ["/usr/local/bin/openhands-agent-server"]
+
+FROM base-image-minimal AS binary-minimal
+ARG USERNAME
+COPY --chown=${USERNAME}:${USERNAME} --from=binary-builder /agent-server/dist/openhands-agent-server /usr/local/bin/openhands-agent-server
+RUN chmod +x /usr/local/bin/openhands-agent-server
+# Fix library path to use system GCC libraries instead of bundled ones
+ENV LD_LIBRARY_PATH=/usr/lib/aarch64-linux-gnu:/usr/lib:/usr/lib/x86_64-linux-gnu:$LD_LIBRARY_PATH
+ENTRYPOINT ["/usr/local/bin/openhands-agent-server"]