Add docker_runtime based on eventstream

Provided working example files for building and running custom sandbox
using the DockerRuntime.

containers/custom-sandbox/.gitignore

@@ -0,0 +1,5 @@
+#
+local
+
+build.sh
+compose.yml

containers/custom-sandbox/README.md

@@ -0,0 +1,33 @@
+# How to build custom Docker sandbox for OpenHands
+
+[Docker](https://docs.docker.com/get-started/docker-overview/) is an open platform for developing, shipping, and running applications.
+
+This folder contains working examples to get you started.
+
+## Build the sandbox
+
+```bash
+# rename the files and make changes as you please
+cp build.example.sh build.sh
+cp compose.example.yml compose.yml
+
+./build.sh <my base image>
+```
+
+## Start up sandbox
+
+```bash
+docker compose up -d
+```
+
+## Update config.toml and restart OpenHands
+
+```toml
+[core]
+runtime="docker"
+
+[sandbox]
+container_name="<sandbox container_name>"
+remote_runtime_api_url="http://<host>:<published sandbox port>/"
+
+```

containers/custom-sandbox/build.example.sh

@@ -0,0 +1,27 @@
+#!/bin/bash
+
+set -euo pipefail
+
+###
+OPENHANDS_WORKSPACE=$(git rev-parse --show-toplevel)
+
+cd "$OPENHANDS_WORKSPACE/" || exit 1
+
+# custom sandbox base image
+IMAGE="${1:-nikolaik/python-nodejs:python3.12-nodejs22}"
+# custom sandbox image tag
+TAG="${2:-custom-sandbox:latest}"
+
+mkdir -p "$OPENHANDS_WORKSPACE/containers/custom-sandbox/local"
+
+poetry run python3 openhands/runtime/utils/runtime_build.py \
+	--base_image "$IMAGE" \
+	--build_folder ./containers/custom-sandbox/local
+
+docker buildx build \
+	--progress "plain" \
+	--tag "$TAG" \
+	--load \
+	./containers/custom-sandbox/local
+
+###

containers/custom-sandbox/compose.example.yml

@@ -0,0 +1,31 @@
+###
+name: sandbox
+services:
+  sandbox:
+    # The container_name must match the name defined in the config.toml
+    container_name: custom-sandbox
+    privileged: true
+    build:
+      context: ./local
+      dockerfile: Dockerfile
+    image: custom-sandbox
+    command: >
+      /openhands/micromamba/bin/micromamba run -n openhands
+      poetry run
+      python -u -m openhands.runtime.action_execution_server 3000
+      --working-dir /workspace
+      --plugins agent_skills jupyter
+      --username openhands
+    # the publicly exposed port 8000 must match the port in remote_runtime_api_url defined in the config.toml
+    ports:
+      - "8000:3000"
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+      - workspace-data:/workspace
+    pull_policy: never
+
+##
+volumes:
+  workspace-data:
+
+###

containers/custom-sandbox/config.example.toml

@@ -0,0 +1,10 @@
+[core]
+runtime="docker"
+
+[sandbox]
+container_name="custom-sandbox"
+remote_runtime_api_url="http://host.docker.internal:8000/"
+
+docker_url="unix:///var/run/docker.sock"
+
+###

openhands/core/config/sandbox_config.py

@@ -32,6 +32,8 @@ class SandboxConfig:
         browsergym_eval_env: The BrowserGym environment to use for evaluation.
             Default is None for general purpose browsing. Check evaluation/miniwob and evaluation/webarena for examples.
         platform: The platform on which the image should be built. Default is None.
+        container_name: The name of the container. Default is None.
+        docker_url: The URL for the Docker daemon. Default is unix:///var/run/docker.sock.
     """
 
     remote_runtime_api_url: str = 'http://localhost:8000'
@@ -53,6 +55,8 @@ class SandboxConfig:
     runtime_startup_env_vars: dict[str, str] = field(default_factory=dict)
     browsergym_eval_env: str | None = None
     platform: str | None = None
+    container_name: str | None = None
+    docker_url: str | None = None
 
     def defaults_to_dict(self) -> dict:
         """Serialize fields to a dict for the frontend, including type hints, defaults, and whether it's optional."""

openhands/runtime/__init__.py

@@ -21,6 +21,11 @@ def get_runtime_cls(name: str):
         return ModalRuntime
     elif name == 'runloop':
         return RunloopRuntime
+    elif name == 'docker':
+        logger.info('Using custom DockerRuntime')
+        from openhands.runtime.impl.docker.docker_runtime import DockerRuntime
+
+        return DockerRuntime
     else:
         raise ValueError(f'Runtime {name} not supported')