openhands-workspace 1.0.0__py3-none-any.whl

openhands/workspace/__init__.py

@@ -0,0 +1,10 @@
+"""OpenHands Workspace - Docker and container-based workspace implementations."""
+
+from .docker import DockerWorkspace
+from .remote_api import APIRemoteWorkspace
+
+
+__all__ = [
+    "DockerWorkspace",
+    "APIRemoteWorkspace",
+]

openhands/workspace/docker/__init__.py

@@ -0,0 +1,6 @@
+"""Docker workspace implementation."""
+
+from .workspace import DockerWorkspace
+
+
+__all__ = ["DockerWorkspace"]

openhands/workspace/docker/workspace.py

@@ -0,0 +1,339 @@
+"""Docker-based remote workspace implementation."""
+
+import os
+import subprocess
+import sys
+import threading
+import time
+import uuid
+from typing import Any
+from urllib.request import urlopen
+
+from pydantic import Field, PrivateAttr, model_validator
+
+from openhands.agent_server.docker.build import (
+    BuildOptions,
+    PlatformType,
+    TargetType,
+    build,
+)
+from openhands.sdk.logger import get_logger
+from openhands.sdk.utils.command import execute_command
+from openhands.sdk.workspace import RemoteWorkspace
+
+
+logger = get_logger(__name__)
+
+
+def check_port_available(port: int) -> bool:
+    """Check if a port is available for binding."""
+    import socket
+
+    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    try:
+        sock.bind(("0.0.0.0", port))
+        return True
+    except OSError:
+        time.sleep(0.1)
+        return False
+    finally:
+        sock.close()
+
+
+def find_available_tcp_port(
+    min_port: int = 30000, max_port: int = 39999, max_attempts: int = 50
+) -> int:
+    """Find an available TCP port in a specified range."""
+    import random
+
+    rng = random.SystemRandom()
+    ports = list(range(min_port, max_port + 1))
+    rng.shuffle(ports)
+
+    for port in ports[:max_attempts]:
+        if check_port_available(port):
+            return port
+    return -1
+
+
+class DockerWorkspace(RemoteWorkspace):
+    """Remote workspace that sets up and manages a Docker container.
+
+    This workspace creates a Docker container running the OpenHands agent server,
+    waits for it to become healthy, and then provides remote workspace operations
+    through the container's HTTP API.
+
+    Example:
+        with DockerWorkspace(base_image="python:3.12") as workspace:
+            result = workspace.execute_command("ls -la")
+    """
+
+    # Override parent fields with defaults
+    working_dir: str = Field(
+        default="/workspace",
+        description="Working directory inside the container.",
+    )
+    host: str = Field(
+        default="",
+        description=("Remote host URL (set automatically during container startup)."),
+    )
+
+    # Docker-specific configuration
+    base_image: str | None = Field(
+        default=None,
+        description="Base Docker image to use for the agent server container. "
+        "Mutually exclusive with server_image.",
+    )
+    server_image: str | None = Field(
+        default=None,
+        description=(
+            "Pre-built agent server image to use. If None, builds from base_image."
+            "Mutually exclusive with base_image."
+        ),
+    )
+    host_port: int | None = Field(
+        default=None,
+        description="Port to bind the container to. If None, finds available port.",
+    )
+    forward_env: list[str] = Field(
+        default_factory=lambda: ["DEBUG"],
+        description="Environment variables to forward to the container.",
+    )
+    mount_dir: str | None = Field(
+        default=None,
+        description="Optional host directory to mount into the container.",
+    )
+    detach_logs: bool = Field(
+        default=True, description="Whether to stream Docker logs in background."
+    )
+    target: TargetType = Field(
+        default="source", description="Build target for the Docker image."
+    )
+    platform: PlatformType = Field(
+        default="linux/amd64", description="Platform for the Docker image."
+    )
+    extra_ports: bool = Field(
+        default=False,
+        description="Whether to expose additional ports (VSCode, VNC).",
+    )
+
+    _container_id: str | None = PrivateAttr(default=None)
+    _logs_thread: threading.Thread | None = PrivateAttr(default=None)
+    _stop_logs: threading.Event = PrivateAttr(default_factory=threading.Event)
+    _image: str = PrivateAttr()
+
+    @model_validator(mode="after")
+    def _validate_images(self):
+        """Ensure exactly one of base_image or server_image is provided; cache it."""
+        if (self.base_image is None) == (self.server_image is None):
+            raise ValueError(
+                "Exactly one of 'base_image' or 'server_image' must be set."
+            )
+        return self
+
+    def model_post_init(self, context: Any) -> None:
+        """Set up the Docker container and initialize the remote workspace."""
+        # Determine port
+        if self.host_port is None:
+            self.host_port = find_available_tcp_port()
+        else:
+            self.host_port = int(self.host_port)
+
+        if not check_port_available(self.host_port):
+            raise RuntimeError(f"Port {self.host_port} is not available")
+
+        if self.extra_ports:
+            if not check_port_available(self.host_port + 1):
+                raise RuntimeError(
+                    f"Port {self.host_port + 1} is not available for VSCode"
+                )
+            if not check_port_available(self.host_port + 2):
+                raise RuntimeError(
+                    f"Port {self.host_port + 2} is not available for VNC"
+                )
+
+        # Ensure docker is available
+        docker_ver = execute_command(["docker", "version"]).returncode
+        if docker_ver != 0:
+            raise RuntimeError(
+                "Docker is not available. Please install and start "
+                "Docker Desktop/daemon."
+            )
+
+        # Build image if needed
+
+        if self.base_image:
+            if "ghcr.io/openhands/agent-server" in self.base_image:
+                raise RuntimeError(
+                    "base_image cannot be a pre-built agent-server image. "
+                    "Use server_image=... instead."
+                )
+            build_opts = BuildOptions(
+                base_image=self.base_image,
+                target=self.target,
+                platforms=[self.platform],
+                push=False,
+            )
+            tags = build(opts=build_opts)
+            assert tags and len(tags) > 0, "Build failed, no image tags returned"
+            self._image = tags[0]
+
+        elif self.server_image:
+            self._image = self.server_image
+        else:
+            raise RuntimeError("Unreachable: one of base_image or server_image is set")
+
+        # Prepare Docker run flags
+        flags: list[str] = []
+        for key in self.forward_env:
+            if key in os.environ:
+                flags += ["-e", f"{key}={os.environ[key]}"]
+
+        if self.mount_dir:
+            mount_path = "/workspace"
+            flags += ["-v", f"{self.mount_dir}:{mount_path}"]
+            logger.info(
+                "Mounting host dir %s to container path %s",
+                self.mount_dir,
+                mount_path,
+            )
+
+        ports = ["-p", f"{self.host_port}:8000"]
+        if self.extra_ports:
+            ports += [
+                "-p",
+                f"{self.host_port + 1}:8001",  # VSCode
+                "-p",
+                f"{self.host_port + 2}:8002",  # Desktop VNC
+            ]
+        flags += ports
+
+        # Run container
+        run_cmd = [
+            "docker",
+            "run",
+            "-d",
+            "--platform",
+            self.platform,
+            "--rm",
+            "--name",
+            f"agent-server-{uuid.uuid4()}",
+            *flags,
+            self._image,
+            "--host",
+            "0.0.0.0",
+            "--port",
+            "8000",
+        ]
+        proc = execute_command(run_cmd)
+        if proc.returncode != 0:
+            raise RuntimeError(f"Failed to run docker container: {proc.stderr}")
+
+        self._container_id = proc.stdout.strip()
+        logger.info("Started container: %s", self._container_id)
+
+        # Optionally stream logs in background
+        if self.detach_logs:
+            self._logs_thread = threading.Thread(
+                target=self._stream_docker_logs, daemon=True
+            )
+            self._logs_thread.start()
+
+        # Set host for RemoteWorkspace to use
+        # The container exposes port 8000, mapped to self.host_port
+        # Override parent's host initialization
+        object.__setattr__(self, "host", f"http://localhost:{self.host_port}")
+        object.__setattr__(self, "api_key", None)
+
+        # Wait for container to be healthy
+        self._wait_for_health()
+        logger.info("Docker workspace is ready at %s", self.host)
+
+        # Now initialize the parent RemoteWorkspace with the container URL
+        super().model_post_init(context)
+
+    def _stream_docker_logs(self) -> None:
+        """Stream Docker logs to stdout in the background."""
+        if not self._container_id:
+            return
+        try:
+            p = subprocess.Popen(
+                ["docker", "logs", "-f", self._container_id],
+                stdout=subprocess.PIPE,
+                stderr=subprocess.STDOUT,
+                text=True,
+            )
+            if p.stdout is None:
+                return
+            for line in iter(p.stdout.readline, ""):
+                if self._stop_logs.is_set():
+                    break
+                if line:
+                    sys.stdout.write(f"[DOCKER] {line}")
+                    sys.stdout.flush()
+        except Exception as e:
+            sys.stderr.write(f"Error streaming docker logs: {e}\n")
+        finally:
+            try:
+                self._stop_logs.set()
+            except Exception:
+                pass
+
+    def _wait_for_health(self, timeout: float = 120.0) -> None:
+        """Wait for the Docker container to become healthy."""
+        start = time.time()
+        health_url = f"http://127.0.0.1:{self.host_port}/health"
+
+        while time.time() - start < timeout:
+            try:
+                with urlopen(health_url, timeout=1.0) as resp:
+                    if 200 <= getattr(resp, "status", 200) < 300:
+                        return
+            except Exception:
+                pass
+
+            # Check if container is still running
+            if self._container_id:
+                ps = execute_command(
+                    [
+                        "docker",
+                        "inspect",
+                        "-f",
+                        "{{.State.Running}}",
+                        self._container_id,
+                    ]
+                )
+                if ps.stdout.strip() != "true":
+                    logs = execute_command(["docker", "logs", self._container_id])
+                    msg = (
+                        "Container stopped unexpectedly. Logs:\n"
+                        f"{logs.stdout}\n{logs.stderr}"
+                    )
+                    raise RuntimeError(msg)
+            time.sleep(1)
+        raise RuntimeError("Container failed to become healthy in time")
+
+    def __enter__(self) -> "DockerWorkspace":
+        """Context manager entry - returns the workspace itself."""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:  # type: ignore[no-untyped-def]
+        """Context manager exit - cleans up the Docker container."""
+        self.cleanup()
+
+    def __del__(self) -> None:
+        """Clean up the Docker container when the workspace is destroyed."""
+        self.cleanup()
+
+    def cleanup(self) -> None:
+        """Stop and remove the Docker container."""
+        if self._container_id:
+            # Stop logs streaming
+            self._stop_logs.set()
+            if self._logs_thread and self._logs_thread.is_alive():
+                self._logs_thread.join(timeout=2)
+
+            # Stop and remove the container
+            logger.info("Stopping container: %s", self._container_id)
+            execute_command(["docker", "stop", self._container_id])
+            self._container_id = None

openhands/workspace/remote_api/__init__.py

@@ -0,0 +1,6 @@
+"""Runtime API workspace implementation."""
+
+from .workspace import APIRemoteWorkspace
+
+
+__all__ = ["APIRemoteWorkspace"]

openhands/workspace/remote_api/workspace.py

@@ -0,0 +1,296 @@
+"""API-based remote workspace implementation using runtime API."""
+
+import uuid
+from typing import Any
+from urllib.request import urlopen
+
+import httpx
+import tenacity
+from pydantic import Field, PrivateAttr
+
+from openhands.sdk.logger import get_logger
+from openhands.sdk.workspace.remote.base import RemoteWorkspace
+
+
+logger = get_logger(__name__)
+
+
+class APIRemoteWorkspace(RemoteWorkspace):
+    """Remote workspace using OpenHands runtime API.
+
+    Runtime API: https://runtime.all-hands.dev/
+
+    Example:
+        workspace = APIRemoteWorkspace(
+            runtime_api_url="https://runtime.eval.all-hands.dev",
+            runtime_api_key="your-api-key",
+            server_image="ghcr.io/openhands/agent-server:lastest-python",
+        )
+    """  # noqa: E501
+
+    # Parent fields
+    working_dir: str = Field(
+        default="/workspace",
+        description="Working directory inside the remote workspace",
+    )
+    host: str = Field(
+        default="undefined",
+        description="The remote host URL for the workspace."
+        " It will be set to the runtime URL after connecting.",
+    )
+
+    # Runtime API fields
+    runtime_api_url: str = Field(description="Base URL of the runtime API")
+    runtime_api_key: str = Field(description="API key for authentication")
+    server_image: str = Field(
+        description="Container image for the agent server. "
+        "It must be a public image or in a registry accessible by runtime API."
+    )
+    session_id: str | None = Field(
+        default_factory=lambda: f"agent-server-{uuid.uuid4()}",
+        description="Session ID (auto-generated if None)",
+    )
+    resource_factor: int = Field(
+        default=1, description="Resource scaling (1, 2, 4, or 8)"
+    )
+    runtime_class: str | None = Field(
+        default="sysbox", description="Runtime class (e.g., 'sysbox')"
+    )
+    init_timeout: float = Field(
+        default=300.0, description="Runtime init timeout (seconds)"
+    )
+    api_timeout: float = Field(
+        default=60.0, description="API request timeout (seconds)"
+    )
+    keep_alive: bool = Field(default=False, description="Keep runtime alive on cleanup")
+    pause_on_close: bool = Field(
+        default=False, description="Pause instead of stop on cleanup"
+    )
+
+    _runtime_id: str | None = PrivateAttr(default=None)
+    _runtime_url: str | None = PrivateAttr(default=None)
+    _session_api_key: str | None = PrivateAttr(default=None)
+
+    def model_post_init(self, context: Any) -> None:
+        """Set up the remote runtime and initialize the workspace."""
+        if self.resource_factor not in [1, 2, 4, 8]:
+            raise ValueError(
+                f"resource_factor must be 1, 2, 4, or 8, got {self.resource_factor}"
+            )
+
+        self.runtime_api_url = self.runtime_api_url.rstrip("/")
+
+        try:
+            self._start_or_attach_to_runtime()
+            super().model_post_init(context)
+        except Exception:
+            self.cleanup()
+            raise
+
+    def _start_or_attach_to_runtime(self) -> None:
+        """Start or attach to an existing runtime."""
+        if not self._check_existing_runtime():
+            self._start_runtime()
+
+        assert self._runtime_id and self._runtime_url, "Runtime ID/URL not set"
+        self._wait_until_runtime_alive()
+        logger.info(f"Runtime ready at {self._runtime_url}")
+        self.host = self._runtime_url.rstrip("/")
+        self.api_key = self._session_api_key
+
+    def _check_existing_runtime(self) -> bool:
+        """Check if there's an existing runtime for this session."""
+        try:
+            resp = self._send_api_request(
+                "GET", f"{self.runtime_api_url}/sessions/{self.session_id}"
+            )
+            data = resp.json()
+            status = data.get("status")
+            logger.info(f"Runtime status: {status}")
+
+            if status in ("running", "paused"):
+                self._parse_runtime_response(resp)
+                if status == "paused":
+                    try:
+                        self._resume_runtime()
+                    except Exception as e:
+                        logger.error(f"Resume failed: {e}")
+                        return False
+                return True
+            return False
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 404:
+                return False
+            raise
+
+    def _start_runtime(self) -> None:
+        """Start a new runtime."""
+        # For binary target, use the standalone binary
+        payload: dict[str, Any] = {
+            "image": self.server_image,
+            "command": "/usr/local/bin/openhands-agent-server --port 60000",
+            "working_dir": "/",  # Match Dockerfile WORKDIR
+            "environment": {},
+            "session_id": self.session_id,
+            "run_as_user": 10001,
+            "fs_group": 10001,
+            # "environment": {"DEBUG": "true"},
+        }
+
+        if self.runtime_class:
+            payload["runtime_class"] = self.runtime_class
+        if self.resource_factor != 1:
+            payload["resource_factor"] = self.resource_factor
+
+        logger.info(f"Starting runtime with {self.server_image}")
+        logger.info(f"Payload: {payload}")
+        resp = self._send_api_request(
+            "POST",
+            f"{self.runtime_api_url}/start",
+            json=payload,
+            timeout=self.init_timeout,
+        )
+        self._parse_runtime_response(resp)
+        logger.info(f"Runtime {self._runtime_id} at {self._runtime_url}")
+
+    def _resume_runtime(self) -> None:
+        """Resume a paused runtime."""
+        resp = self._send_api_request(
+            "POST",
+            f"{self.runtime_api_url}/resume",
+            json={"runtime_id": self._runtime_id},
+            timeout=self.init_timeout,
+        )
+        self._parse_runtime_response(resp)
+
+    def _parse_runtime_response(self, response: httpx.Response) -> None:
+        """Parse the runtime response and extract connection info."""
+        data = response.json()
+        self._runtime_id = data.get("runtime_id") or data.get("id")
+        self._runtime_url = data.get("url")
+        self._session_api_key = data.get("session_api_key")
+        if not self._runtime_id or not self._runtime_url:
+            raise ValueError(f"Invalid runtime response: {data}")
+
+    @tenacity.retry(
+        stop=tenacity.stop_after_delay(300),
+        wait=tenacity.wait_exponential(multiplier=1, min=2, max=10),
+        retry=tenacity.retry_if_exception_type(RuntimeError),
+        reraise=True,
+    )
+    def _wait_until_runtime_alive(self) -> None:
+        """Wait until the runtime becomes alive and responsive."""
+        logger.info("Waiting for runtime to become alive...")
+
+        resp = self._send_api_request(
+            "GET", f"{self.runtime_api_url}/sessions/{self.session_id}"
+        )
+        data = resp.json()
+        pod_status = data.get("pod_status", "").lower()
+        logger.info(f"Pod status: {pod_status}")
+
+        # Log additional details for debugging
+        if pod_status == "pending":
+            container_statuses = data.get("container_statuses", [])
+            events = data.get("events", [])
+            if container_statuses:
+                logger.warning(f"Container statuses: {container_statuses}")
+            if events:
+                logger.warning(f"Pod events: {events}")
+            logger.debug(f"Full response: {data}")
+
+        restart_count = data.get("restart_count", 0)
+        if restart_count > 0:
+            restart_reasons = data.get("restart_reasons", [])
+            logger.warning(f"Pod restarts: {restart_count}, reasons: {restart_reasons}")
+
+        # Handle different pod states
+        if pod_status == "ready":
+            # Pod is ready, check health endpoint
+            health_url = f"{self._runtime_url}/health"
+            logger.info(f"Checking health at: {health_url}")
+            try:
+                with urlopen(health_url, timeout=5.0) as resp:
+                    status = getattr(resp, "status", 200)
+                    logger.info(f"Health check response: {status}")
+                    if 200 <= status < 300:
+                        logger.info("Runtime is alive!")
+                        return
+                    raise RuntimeError(f"Health check failed with status: {status}")
+            except Exception as e:
+                logger.warning(f"Health check failed: {e}")
+                raise RuntimeError(f"Runtime /health failed: {e}")
+        elif pod_status in ("not found", "pending", "running"):
+            # Transient states - continue retrying
+            logger.debug(f"Runtime not yet ready. Status: {pod_status}")
+            raise RuntimeError(f"Runtime not yet ready (status: {pod_status})")
+        elif pod_status in ("failed", "unknown", "crashloopbackoff"):
+            # Terminal failure states
+            pod_logs = data.get("pod_logs", "")
+            error_msg = f"Runtime failed (status: {pod_status})"
+            if pod_logs:
+                logger.error(f"Pod logs: {pod_logs}")
+                error_msg += f"\nPod logs: {pod_logs}"
+            if pod_status == "crashloopbackoff":
+                error_msg = (
+                    "Runtime crashed and is restarting (possibly OOM). Try again."
+                )
+            raise ValueError(error_msg)
+        else:
+            # Unknown status - log and retry
+            logger.warning(f"Unknown pod status: {pod_status}, full response: {data}")
+            raise RuntimeError(f"Unknown pod status: {pod_status}")
+
+    def _send_api_request(self, method: str, url: str, **kwargs: Any) -> httpx.Response:
+        """Send an API request with error handling."""
+        logger.debug(f"Sending {method} request to {url}")
+        logger.debug(f"Client headers: {self._headers}")
+        response = self.client.request(method, url, **kwargs)
+        try:
+            response.raise_for_status()
+        except httpx.HTTPStatusError:
+            logger.debug(f"Request headers: {response.request.headers}")
+            try:
+                error_detail = response.json()
+                logger.info(f"API request failed: {error_detail}")
+            except Exception:
+                logger.info(f"API request failed: {response.text}")
+            raise
+        return response
+
+    def cleanup(self) -> None:
+        """Clean up the remote runtime."""
+        if not self._runtime_id:
+            return
+
+        try:
+            if self.keep_alive:
+                return
+
+            action = "pause" if self.pause_on_close else "stop"
+            logger.info(f"{action.capitalize()}ing runtime {self._runtime_id}")
+            self._send_api_request(
+                "POST",
+                f"{self.runtime_api_url}/{action}",
+                json={"runtime_id": self._runtime_id},
+                timeout=30.0,
+            )
+        except Exception as e:
+            logger.error(f"Cleanup error: {e}")
+        finally:
+            self._runtime_id = None
+            self._runtime_url = None
+            self._session_api_key = None
+            try:
+                self.client.close()
+            except Exception:
+                pass
+
+    def __del__(self) -> None:
+        self.cleanup()
+
+    def __enter__(self) -> "APIRemoteWorkspace":
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        self.cleanup()

openhands_workspace-1.0.0.dist-info/METADATA

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: openhands-workspace
+Version: 1.0.0
+Summary: OpenHands Workspace - Docker and container-based workspace implementations
+Requires-Python: >=3.12
+Requires-Dist: openhands-sdk
+Requires-Dist: pydantic>=2.11.7

openhands_workspace-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+openhands/workspace/__init__.py,sha256=0UHu2lU1tjXhVcJSU6zQUaa3MLbqOLgGF8WdPSmjCPY,227
+openhands/workspace/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+openhands/workspace/docker/__init__.py,sha256=axwSNLItKWxyxbZ1VuKKTrvnVAxALC9b2ZlTatnBJRE,111
+openhands/workspace/docker/workspace.py,sha256=H1QiQqr_xig0Xcgc4_sDjeTng7XYGNj4aGPpfsS8dx8,11499
+openhands/workspace/remote_api/__init__.py,sha256=RxDLFcveTGG-uLm-PInfxFnYwYPdehRmLf1r0_KTaP4,122
+openhands/workspace/remote_api/workspace.py,sha256=zWXoq80wxIYA-BORl1ebqLzOTSEdJYan4QEqsk_YY0g,11363
+openhands_workspace-1.0.0.dist-info/METADATA,sha256=PylvdehS6-WarDQNKn7SfmZZ6i0RnRq5F6nmTcwE0Fk,232
+openhands_workspace-1.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+openhands_workspace-1.0.0.dist-info/top_level.txt,sha256=jHgVu9I0Blam8BXFgedoGKfglPF8XvW1TsJFIjcgP4E,10
+openhands_workspace-1.0.0.dist-info/RECORD,,

openhands_workspace-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

openhands_workspace-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+openhands