Update workspace_* variables with deprecation warnings and improve documentation

openhands/core/config/openhands_config.py

@@ -76,10 +76,27 @@ class OpenHandsConfig(BaseModel):
     )
 
     # Deprecated parameters - will be removed in a future version
-    workspace_base: str | None = Field(default=None, deprecated=True)
-    workspace_mount_path: str | None = Field(default=None, deprecated=True)
-    workspace_mount_path_in_sandbox: str = Field(default='/workspace', deprecated=True)
-    workspace_mount_rewrite: str | None = Field(default=None, deprecated=True)
+    # Use sandbox.volumes instead, e.g. '/host/path:/workspace:rw'
+    workspace_base: str | None = Field(
+        default=None,
+        deprecated=True,
+        description="DEPRECATED: Use sandbox.volumes instead, e.g. '/host/path:/workspace:rw'",
+    )
+    workspace_mount_path: str | None = Field(
+        default=None,
+        deprecated=True,
+        description="DEPRECATED: Use sandbox.volumes instead, e.g. '/host/path:/workspace:rw'",
+    )
+    workspace_mount_path_in_sandbox: str = Field(
+        default='/workspace',
+        deprecated=True,
+        description="DEPRECATED: Use sandbox.volumes instead, e.g. '/host/path:/workspace:rw'",
+    )
+    workspace_mount_rewrite: str | None = Field(
+        default=None,
+        deprecated=True,
+        description="DEPRECATED: Use sandbox.volumes instead, e.g. '/host/path:/workspace:rw'",
+    )
     # End of deprecated parameters
 
     cache_dir: str = Field(default='/tmp/cache')

openhands/core/config/sandbox_config.py

@@ -85,7 +85,7 @@ class SandboxConfig(BaseModel):
     vscode_port: int | None = Field(default=None)
     volumes: str | None = Field(
         default=None,
-        description="Volume mounts in the format 'host_path:container_path[:mode]', e.g. '/my/host/dir:/workspace:rw'. Multiple mounts can be specified using commas, e.g. '/path1:/workspace/path1,/path2:/workspace/path2:ro'",
+        description="Volume mounts in the format 'host_path:container_path[:mode]', e.g. '/my/host/dir:/workspace:rw'. Multiple mounts can be specified using commas, e.g. '/path1:/workspace/path1,/path2:/workspace/path2:ro'. This replaces the deprecated workspace_base, workspace_mount_path, workspace_mount_path_in_sandbox, and workspace_mount_rewrite variables.",
     )
 
     model_config = {'extra': 'forbid'}

openhands/core/config/utils.py

@@ -307,8 +307,9 @@ def finalize_config(cfg: OpenHandsConfig) -> None:
     # Handle the sandbox.volumes parameter
     if cfg.workspace_base is not None or cfg.workspace_mount_path is not None:
         logger.openhands_logger.warning(
-            'DEPRECATED: The WORKSPACE_BASE and WORKSPACE_MOUNT_PATH environment variables are deprecated. '
-            "Please use RUNTIME_MOUNT instead, e.g. 'RUNTIME_MOUNT=/my/host/dir:/workspace:rw'"
+            'DEPRECATED: The workspace_base, workspace_mount_path, workspace_mount_path_in_sandbox, and workspace_mount_rewrite '
+            'variables are deprecated and will be removed in a future version. '
+            "Please use sandbox.volumes instead, e.g. 'SANDBOX_VOLUMES=/my/host/dir:/workspace:rw'"
         )
     if cfg.sandbox.volumes is not None:
         # Split by commas to handle multiple mounts

openhands/runtime/impl/docker/docker_runtime.py

@@ -1,7 +1,7 @@
 import os
+import typing
 from functools import lru_cache
 from typing import Callable
-import typing
 from uuid import UUID
 
 import docker
@@ -245,10 +245,10 @@ class DockerRuntime(ActionExecutionClient):
                         'mode': mount_mode,
                     }
                     logger.debug(
-                        f'Mount dir (sandbox.volumes): {host_path} to {container_path} with mode: {mount_mode}'
+                        f'Mount dir: {host_path} to {container_path} with mode: {mount_mode}'
                     )
 
-        # Legacy mounting with workspace_* parameters
+        # Legacy mounting with workspace_* parameters (deprecated)
         elif (
             self.config.workspace_mount_path is not None
             and self.config.workspace_mount_path_in_sandbox is not None
@@ -261,7 +261,11 @@ class DockerRuntime(ActionExecutionClient):
                 'mode': mount_mode,
             }
             logger.debug(
-                f'Mount dir (legacy): {self.config.workspace_mount_path} with mode: {mount_mode}'
+                f'Mount dir (using deprecated workspace_* variables): {self.config.workspace_mount_path} with mode: {mount_mode}'
+            )
+            logger.debug(
+                'DEPRECATED: The workspace_* variables are deprecated and will be removed in a future version. '
+                "Please use sandbox.volumes instead, e.g. 'SANDBOX_VOLUMES=/my/host/dir:/workspace:rw'"
             )
 
         return volumes
@@ -283,7 +287,9 @@ class DockerRuntime(ActionExecutionClient):
         self.api_url = f'{self.config.sandbox.local_runtime_url}:{self._container_port}'
 
         use_host_network = self.config.sandbox.use_host_network
-        network_mode: typing.Literal['host'] | None = 'host' if use_host_network else None
+        network_mode: typing.Literal['host'] | None = (
+            'host' if use_host_network else None
+        )
 
         # Initialize port mappings
         port_mapping: dict[str, list[dict[str, str]]] | None = None
@@ -356,7 +362,7 @@ class DockerRuntime(ActionExecutionClient):
 
         try:
             if self.runtime_container_image is None:
-                raise ValueError("Runtime container image is not set")
+                raise ValueError('Runtime container image is not set')
             self.container = self.docker_client.containers.run(
                 self.runtime_container_image,
                 command=command,