openhands-workspace 1.7.1__py3-none-any.whl

openhands/workspace/__init__.py

@@ -0,0 +1,31 @@
+"""OpenHands Workspace - Docker and container-based workspace implementations."""
+
+from typing import TYPE_CHECKING
+
+from openhands.sdk.workspace import PlatformType, TargetType
+
+from .cloud import OpenHandsCloudWorkspace
+from .docker import DockerWorkspace
+from .remote_api import APIRemoteWorkspace
+
+
+if TYPE_CHECKING:
+    from .docker import DockerDevWorkspace
+
+__all__ = [
+    "APIRemoteWorkspace",
+    "DockerDevWorkspace",
+    "DockerWorkspace",
+    "OpenHandsCloudWorkspace",
+    "PlatformType",
+    "TargetType",
+]
+
+
+def __getattr__(name: str):
+    """Lazy import DockerDevWorkspace to avoid build module imports."""
+    if name == "DockerDevWorkspace":
+        from .docker import DockerDevWorkspace
+
+        return DockerDevWorkspace
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

openhands/workspace/cloud/__init__.py

@@ -0,0 +1,6 @@
+"""OpenHands Cloud workspace implementation."""
+
+from .workspace import OpenHandsCloudWorkspace
+
+
+__all__ = ["OpenHandsCloudWorkspace"]

openhands/workspace/cloud/workspace.py

@@ -0,0 +1,314 @@
+"""OpenHands Cloud workspace implementation using Cloud API."""
+
+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__)
+
+# Standard exposed URL names from OpenHands Cloud
+AGENT_SERVER = "AGENT_SERVER"
+
+
+class OpenHandsCloudWorkspace(RemoteWorkspace):
+    """Remote workspace using OpenHands Cloud API.
+
+    This workspace connects to OpenHands Cloud (app.all-hands.dev) to provision
+    and manage sandboxed environments for agent execution.
+
+    Example:
+        workspace = OpenHandsCloudWorkspace(
+            cloud_api_url="https://app.all-hands.dev",
+            cloud_api_key="your-api-key",
+        )
+
+        # With custom sandbox spec
+        workspace = OpenHandsCloudWorkspace(
+            cloud_api_url="https://app.all-hands.dev",
+            cloud_api_key="your-api-key",
+            sandbox_spec_id="ghcr.io/openhands/agent-server:main-python",
+        )
+    """
+
+    # Parent fields
+    working_dir: str = Field(
+        default="/workspace/project",
+        description="Working directory inside the sandbox",
+    )
+    host: str = Field(
+        default="undefined",
+        description="The agent server URL. Set automatically after sandbox starts.",
+    )
+
+    # Cloud API fields
+    cloud_api_url: str = Field(
+        description="Base URL of OpenHands Cloud API (e.g., https://app.all-hands.dev)"
+    )
+    cloud_api_key: str = Field(
+        description="API key for authenticating with OpenHands Cloud"
+    )
+    sandbox_spec_id: str | None = Field(
+        default=None,
+        description="Optional sandbox specification ID (e.g., container image)",
+    )
+
+    # Lifecycle options
+    init_timeout: float = Field(
+        default=300.0, description="Sandbox initialization timeout in seconds"
+    )
+    api_timeout: float = Field(
+        default=60.0, description="API request timeout in seconds"
+    )
+    keep_alive: bool = Field(
+        default=False,
+        description="If True, keep sandbox alive on cleanup instead of deleting",
+    )
+
+    # Private state
+    _sandbox_id: str | None = PrivateAttr(default=None)
+    _session_api_key: str | None = PrivateAttr(default=None)
+    _exposed_urls: list[dict[str, Any]] | None = PrivateAttr(default=None)
+
+    @property
+    def client(self) -> httpx.Client:
+        """Override client property to use api_timeout for HTTP requests."""
+        client = self._client
+        if client is None:
+            timeout = httpx.Timeout(
+                connect=10.0,
+                read=self.api_timeout,
+                write=10.0,
+                pool=10.0,
+            )
+            client = httpx.Client(
+                base_url=self.host, timeout=timeout, headers=self._headers
+            )
+            self._client = client
+        return client
+
+    @property
+    def _api_headers(self) -> dict[str, str]:
+        """Headers for Cloud API requests.
+
+        Uses Bearer token authentication as per OpenHands Cloud API.
+        """
+        return {"Authorization": f"Bearer {self.cloud_api_key}"}
+
+    def model_post_init(self, context: Any) -> None:
+        """Set up the sandbox and initialize the workspace."""
+        self.cloud_api_url = self.cloud_api_url.rstrip("/")
+
+        try:
+            self._start_sandbox()
+            super().model_post_init(context)
+        except Exception:
+            self.cleanup()
+            raise
+
+    def _start_sandbox(self) -> None:
+        """Start a new sandbox via Cloud API."""
+        logger.info("Starting sandbox via OpenHands Cloud API...")
+
+        # Build request params
+        params: dict[str, str] = {}
+        if self.sandbox_spec_id:
+            params["sandbox_spec_id"] = self.sandbox_spec_id
+
+        # POST /api/v1/sandboxes to start a new sandbox
+        resp = self._send_api_request(
+            "POST",
+            f"{self.cloud_api_url}/api/v1/sandboxes",
+            params=params if params else None,
+            timeout=self.init_timeout,
+        )
+        data = resp.json()
+
+        self._sandbox_id = data["id"]
+        self._session_api_key = data.get("session_api_key")
+        logger.info(
+            f"Sandbox {self._sandbox_id} created, waiting for it to be ready..."
+        )
+
+        # Wait for sandbox to become RUNNING
+        self._wait_until_sandbox_ready()
+
+        # Extract agent server URL from exposed_urls
+        agent_server_url = self._get_agent_server_url()
+        if not agent_server_url:
+            raise ValueError(
+                f"Agent server URL not found in sandbox {self._sandbox_id}"
+            )
+
+        logger.info(f"Sandbox ready at {agent_server_url}")
+
+        # Set host and api_key for RemoteWorkspace operations
+        self.host = agent_server_url.rstrip("/")
+        self.api_key = self._session_api_key
+
+        # Reset HTTP client with new host and API key
+        self.reset_client()
+
+        # Verify client is properly initialized
+        assert self.client is not None
+        assert self.client.base_url == self.host
+
+    @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_sandbox_ready(self) -> None:
+        """Wait until the sandbox becomes RUNNING and responsive."""
+        logger.debug("Checking sandbox status...")
+
+        # GET /api/v1/sandboxes?id=<sandbox_id>
+        resp = self._send_api_request(
+            "GET",
+            f"{self.cloud_api_url}/api/v1/sandboxes",
+            params={"id": self._sandbox_id},
+        )
+        sandboxes = resp.json()
+
+        if not sandboxes or sandboxes[0] is None:
+            raise RuntimeError(f"Sandbox {self._sandbox_id} not found")
+
+        sandbox = sandboxes[0]
+        status = sandbox.get("status")
+        logger.info(f"Sandbox status: {status}")
+
+        if status == "RUNNING":
+            # Update session_api_key and exposed_urls from response
+            self._session_api_key = sandbox.get("session_api_key")
+            self._exposed_urls = sandbox.get("exposed_urls") or []
+
+            # Verify agent server is accessible
+            agent_server_url = self._get_agent_server_url()
+            if agent_server_url:
+                self._check_agent_server_health(agent_server_url)
+            return
+
+        elif status == "STARTING":
+            raise RuntimeError("Sandbox still starting")
+
+        elif status in ("ERROR", "MISSING"):
+            raise ValueError(f"Sandbox failed with status: {status}")
+
+        elif status == "PAUSED":
+            # Try to resume the sandbox
+            logger.info("Sandbox is paused, attempting to resume...")
+            self._resume_sandbox()
+            raise RuntimeError("Sandbox resuming, waiting for RUNNING status")
+
+        else:
+            logger.warning(f"Unknown sandbox status: {status}")
+            raise RuntimeError(f"Unknown sandbox status: {status}")
+
+    def _check_agent_server_health(self, agent_server_url: str) -> None:
+        """Check if the agent server is healthy."""
+        health_url = f"{agent_server_url.rstrip('/')}/health"
+        logger.debug(f"Checking agent server health at: {health_url}")
+        try:
+            with urlopen(health_url, timeout=5.0) as resp:
+                status = getattr(resp, "status", 200)
+                if 200 <= status < 300:
+                    logger.debug("Agent server is healthy")
+                    return
+                raise RuntimeError(f"Health check failed with status: {status}")
+        except Exception as e:
+            logger.warning(f"Health check failed: {e}")
+            raise RuntimeError(f"Agent server health check failed: {e}")
+
+    def _resume_sandbox(self) -> None:
+        """Resume a paused sandbox."""
+        if not self._sandbox_id:
+            return
+
+        logger.info(f"Resuming sandbox {self._sandbox_id}...")
+        self._send_api_request(
+            "POST",
+            f"{self.cloud_api_url}/api/v1/sandboxes/{self._sandbox_id}/resume",
+            timeout=self.init_timeout,
+        )
+
+    def _get_agent_server_url(self) -> str | None:
+        """Extract agent server URL from exposed_urls."""
+        if not self._exposed_urls:
+            return None
+
+        for url_info in self._exposed_urls:
+            if url_info.get("name") == AGENT_SERVER:
+                return url_info.get("url")
+
+        return None
+
+    def _send_api_request(self, method: str, url: str, **kwargs: Any) -> httpx.Response:
+        """Send an API request to the Cloud API with error handling."""
+        logger.debug(f"Sending {method} request to {url}")
+
+        # Ensure headers include API key
+        headers = kwargs.pop("headers", {})
+        headers.update(self._api_headers)
+
+        # Use a separate client for API requests (not the agent server client)
+        timeout = kwargs.pop("timeout", self.api_timeout)
+        with httpx.Client(timeout=timeout) as api_client:
+            response = api_client.request(method, url, headers=headers, **kwargs)
+
+        try:
+            response.raise_for_status()
+        except httpx.HTTPStatusError:
+            try:
+                error_detail = response.json()
+                logger.error(f"Cloud API request failed: {error_detail}")
+            except Exception:
+                logger.error(f"Cloud API request failed: {response.text}")
+            raise
+
+        return response
+
+    def cleanup(self) -> None:
+        """Clean up the sandbox by deleting it."""
+        if not self._sandbox_id:
+            return
+
+        try:
+            if self.keep_alive:
+                logger.info(f"Keeping sandbox {self._sandbox_id} alive")
+                return
+
+            logger.info(f"Deleting sandbox {self._sandbox_id}...")
+            self._send_api_request(
+                "DELETE",
+                f"{self.cloud_api_url}/api/v1/sandboxes",
+                params={"sandbox_id": self._sandbox_id},
+                timeout=30.0,
+            )
+            logger.info(f"Sandbox {self._sandbox_id} deleted")
+        except Exception as e:
+            logger.warning(f"Cleanup error: {e}")
+        finally:
+            self._sandbox_id = None
+            self._session_api_key = None
+            self._exposed_urls = None
+            try:
+                if self._client:
+                    self._client.close()
+            except Exception:
+                pass
+
+    def __del__(self) -> None:
+        self.cleanup()
+
+    def __enter__(self) -> "OpenHandsCloudWorkspace":
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        self.cleanup()

openhands/workspace/docker/__init__.py

@@ -0,0 +1,20 @@
+"""Docker workspace implementation."""
+
+from typing import TYPE_CHECKING
+
+from .workspace import DockerWorkspace
+
+
+if TYPE_CHECKING:
+    from .dev_workspace import DockerDevWorkspace
+
+__all__ = ["DockerWorkspace", "DockerDevWorkspace"]
+
+
+def __getattr__(name: str):
+    """Lazy import DockerDevWorkspace to avoid build module imports."""
+    if name == "DockerDevWorkspace":
+        from .dev_workspace import DockerDevWorkspace
+
+        return DockerDevWorkspace
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

openhands/workspace/docker/dev_workspace.py

@@ -0,0 +1,116 @@
+"""Docker development workspace with on-the-fly image building capability."""
+
+from pydantic import Field, model_validator
+
+from openhands.sdk.workspace import PlatformType, TargetType
+
+from .workspace import DockerWorkspace
+
+
+class DockerDevWorkspace(DockerWorkspace):
+    """Docker workspace with on-the-fly image building capability.
+
+    This workspace extends DockerWorkspace to support building Docker images
+    on-the-fly from a base image. This is useful for development and testing
+    scenarios where you need to customize the agent server environment.
+
+    Note: This class requires the OpenHands SDK workspace structure and should
+    only be used within the OpenHands development environment or when you have
+    the full SDK source code available.
+
+    For production use cases with pre-built images, use DockerWorkspace instead.
+
+    Example:
+        with DockerDevWorkspace(
+            base_image="python:3.12",
+            target="source"
+        ) as workspace:
+            result = workspace.execute_command("ls -la")
+    """
+
+    # Add base_image support
+    base_image: str | None = Field(
+        default=None,
+        description=(
+            "Base Docker image to build the agent server from. "
+            "Mutually exclusive with server_image."
+        ),
+    )
+
+    # Add build-specific options
+    target: TargetType = Field(
+        default="source", description="Build target for the Docker image."
+    )
+
+    @model_validator(mode="after")
+    def _validate_images(self):
+        """Ensure exactly one of base_image or server_image is provided."""
+        if (self.base_image is None) == (self.server_image is None):
+            raise ValueError(
+                "Exactly one of 'base_image' or 'server_image' must be set."
+            )
+        if self.base_image and "ghcr.io/openhands/agent-server" in self.base_image:
+            raise ValueError(
+                "base_image cannot be a pre-built agent-server image. "
+                "Use server_image=... instead."
+            )
+        return self
+
+    @staticmethod
+    def _build_image_from_base(
+        *, base_image: str, target: TargetType, platform: PlatformType
+    ) -> str:
+        """Build a Docker image from a base image.
+
+        Args:
+            base_image: The base Docker image to build from.
+            target: The build target (e.g., 'source', 'dev').
+            platform: The platform to build for (e.g., 'linux/amd64').
+
+        Returns:
+            The built Docker image tag.
+
+        Raises:
+            RuntimeError: If the base_image is a pre-built agent-server image
+                or if the build fails.
+        """
+        from openhands.agent_server.docker.build import BuildOptions, build
+
+        if "ghcr.io/openhands/agent-server" in base_image:
+            raise RuntimeError(
+                "base_image cannot be a pre-built agent-server image. "
+                "Use server_image=... instead."
+            )
+
+        build_opts = BuildOptions(
+            base_image=base_image,
+            target=target,
+            platforms=[platform],
+            push=False,
+        )
+        tags = build(opts=build_opts)
+        if not tags:
+            raise RuntimeError("Build failed, no image tags returned")
+        return tags[0]
+
+    def get_image(self) -> str:
+        """Build the image if base_image is provided, otherwise use server_image.
+
+        This overrides the parent method to add on-the-fly image building
+        capability.
+
+        Returns:
+            The Docker image tag to use.
+        """
+        if self.base_image:
+            # Build the image from base_image
+            return self._build_image_from_base(
+                base_image=self.base_image,
+                target=self.target,
+                platform=self.platform,
+            )
+        elif self.server_image:
+            # Use pre-built image
+            return self.server_image
+        else:
+            raise ValueError("Either base_image or server_image must be set")

openhands/workspace/docker/workspace.py

@@ -0,0 +1,358 @@
+"""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.sdk.logger import get_logger
+from openhands.sdk.utils.command import execute_command
+from openhands.sdk.workspace import PlatformType, 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 a pre-built OpenHands agent
+    server image, waits for it to become healthy, and then provides remote workspace
+    operations through the container's HTTP API.
+
+    Note: This class only works with pre-built images. To build images on-the-fly
+    from a base image, use DockerDevWorkspace instead.
+
+    Example:
+        with DockerWorkspace(
+            server_image="ghcr.io/openhands/agent-server:latest"
+        ) 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
+    server_image: str | None = Field(
+        default=None,
+        description="Pre-built agent server image to use.",
+    )
+    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."
+    )
+    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).",
+    )
+    enable_gpu: bool = Field(
+        default=False,
+        description="Whether to enable GPU support with --gpus all.",
+    )
+    cleanup_image: bool = Field(
+        default=False,
+        description="Whether to delete the Docker image when cleaning up workspace.",
+    )
+
+    _container_id: str | None = PrivateAttr(default=None)
+    _image_name: str | None = PrivateAttr(default=None)
+    _logs_thread: threading.Thread | None = PrivateAttr(default=None)
+    _stop_logs: threading.Event = PrivateAttr(default_factory=threading.Event)
+
+    @model_validator(mode="after")
+    def _validate_server_image(self):
+        """Ensure server_image is set when using DockerWorkspace directly."""
+        if self.__class__ is DockerWorkspace and self.server_image is None:
+            raise ValueError("server_image must be provided")
+        return self
+
+    def model_post_init(self, context: Any) -> None:
+        """Set up the Docker container and initialize the remote workspace."""
+        # Subclasses should call get_image() to get the image to use
+        # This allows them to build or prepare the image before container startup
+        image = self.get_image()
+        self._start_container(image, context)
+
+    def get_image(self) -> str:
+        """Get the Docker image to use for the container.
+
+        Subclasses can override this to provide custom image resolution logic
+        (e.g., building images on-the-fly).
+
+        Returns:
+            The Docker image tag to use.
+        """
+        if self.server_image is None:
+            raise ValueError("server_image must be set")
+        return self.server_image
+
+    def _start_container(self, image: str, context: Any) -> None:
+        """Start the Docker container with the given image.
+
+        This method handles all container lifecycle: port allocation, Docker
+        validation, container creation, health checks, and RemoteWorkspace
+        initialization.
+
+        Args:
+            image: The Docker image tag to use.
+            context: The Pydantic context from model_post_init.
+        """
+        # Store the image name for cleanup
+        self._image_name = image
+
+        # 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."
+            )
+
+        # 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
+
+        # Add GPU support if enabled
+        if self.enable_gpu:
+            flags += ["--gpus", "all"]
+
+        # Run container
+        run_cmd = [
+            "docker",
+            "run",
+            "-d",
+            "--platform",
+            self.platform,
+            "--rm",
+            "--name",
+            f"agent-server-{uuid.uuid4()}",
+            *flags,
+            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
+
+        # Optionally delete the Docker image
+        if self.cleanup_image and self._image_name:
+            logger.info("Deleting Docker image: %s", self._image_name)
+            result = execute_command(["docker", "rmi", "-f", self._image_name])
+            if result.returncode == 0:
+                logger.info("Successfully deleted image: %s", self._image_name)
+            else:
+                logger.warning(
+                    "Failed to delete image %s: %s", self._image_name, result.stderr
+                )
+            self._image_name = 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,356 @@
+"""API-based remote workspace implementation using runtime API."""
+
+import uuid
+from typing import Any, Literal
+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."
+    )
+    image_pull_policy: Literal["Always", "IfNotPresent", "Never"] = Field(
+        default="IfNotPresent",
+        description="Image pull policy for the 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-runc", 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"
+    )
+    target_type: Literal["binary", "source"] = Field(
+        default="binary",
+        description="Type of agent server target (binary or source)",
+    )
+
+    _runtime_id: str | None = PrivateAttr(default=None)
+    _runtime_url: str | None = PrivateAttr(default=None)
+    _session_api_key: str | None = PrivateAttr(default=None)
+
+    @property
+    def client(self) -> httpx.Client:
+        """Override client property to use api_timeout for HTTP requests."""
+        client = self._client
+        if client is None:
+            # Use api_timeout for the read timeout to allow longer operations
+            timeout = httpx.Timeout(
+                connect=10.0,
+                read=self.api_timeout,
+                write=10.0,
+                pool=10.0,
+            )
+            client = httpx.Client(
+                base_url=self.host, timeout=timeout, headers=self._headers
+            )
+            self._client = client
+        return client
+
+    @property
+    def _api_headers(self):
+        """Headers for runtime API requests."
+
+        This is used to manage new container runtimes via Runtime API.
+
+        For actual interaction with the remote agent server, the
+        `client` property is used, which includes the session API key
+        defined by ._headers property.
+        """
+        headers = {}
+        if self.runtime_api_key:
+            headers["X-API-Key"] = self.runtime_api_key
+        return headers
+
+    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
+        # Reset HTTP client with new host and API key
+        self.reset_client()
+        # Verify client is properly initialized
+        assert self.client is not None
+        assert self.client.base_url == self.host
+
+    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}",
+                headers=self._api_headers,
+            )
+            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."""
+        if self.target_type == "binary":
+            executable = "/usr/local/bin/openhands-agent-server"
+        else:
+            executable = "/agent-server/.venv/bin/python -m openhands.agent_server"
+        # For binary target, use the standalone binary
+        payload: dict[str, Any] = {
+            "image": self.server_image,
+            "command": f"{executable} --port 60000",
+            "working_dir": "/",  # Match Dockerfile WORKDIR
+            "environment": {},
+            "session_id": self.session_id,
+            "run_as_user": 10001,
+            "fs_group": 10001,
+            "image_pull_policy": self.image_pull_policy,
+        }
+
+        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,
+            headers=self._api_headers,
+        )
+        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,
+            headers=self._api_headers,
+        )
+        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}",
+            headers=self._api_headers,
+        )
+        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"Request kwargs: {kwargs.keys()}")
+
+        response = self.client.request(method, url, **kwargs)
+        try:
+            response.raise_for_status()
+        except httpx.HTTPStatusError:
+            # Log only header keys, not values (to avoid exposing API keys)
+            header_keys = list(response.request.headers.keys())
+            logger.debug(f"Request header keys: {header_keys}")
+            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,
+                headers=self._api_headers,
+            )
+        except Exception as e:
+            logger.warning(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.7.1.dist-info/METADATA

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: openhands-workspace
+Version: 1.7.1
+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.7.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+openhands/workspace/__init__.py,sha256=yr1_q7SLXTOt7FyAilUWLdH5KY6N1qjMytQZMFoy5W0,819
+openhands/workspace/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+openhands/workspace/cloud/__init__.py,sha256=Ck8mDOf1YF4M1vn-vNkqxqGaEgB1qsQ7lLT9lTaS6gM,136
+openhands/workspace/cloud/workspace.py,sha256=zB1gfKMo26J_I14_7eke1TVIDLr6UlymOtrxdhOtOyU,10782
+openhands/workspace/docker/__init__.py,sha256=vhMjEqbG5NmwL2UINxtAZj_y5lKlaLlqUNz2f3owJVQ,539
+openhands/workspace/docker/dev_workspace.py,sha256=5HZFXhtP9UZRST76E705TmYtVJcYbJIyq38GQFxiefE,3993
+openhands/workspace/docker/workspace.py,sha256=FpCh2ElSYjDyp0VmA3JvmpK4O6_5gcMoUJdrmuel0CI,12400
+openhands/workspace/remote_api/__init__.py,sha256=RxDLFcveTGG-uLm-PInfxFnYwYPdehRmLf1r0_KTaP4,122
+openhands/workspace/remote_api/workspace.py,sha256=F8utWHzDyCeaXVjscuC3A-GF0O1LRrK1j82OJE7wFZI,13574
+openhands_workspace-1.7.1.dist-info/METADATA,sha256=8S_XdVax1Ng9LMWR3P52Rf6S5BWps0AvdxHMsWrKmoQ,232
+openhands_workspace-1.7.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+openhands_workspace-1.7.1.dist-info/top_level.txt,sha256=jHgVu9I0Blam8BXFgedoGKfglPF8XvW1TsJFIjcgP4E,10
+openhands_workspace-1.7.1.dist-info/RECORD,,

openhands_workspace-1.7.1.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.7.1.dist-info/top_level.txt

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