Add support for custom volume mounts in DockerRuntime

[Shimada666]

What problem or use case are you trying to solve?
Currently, the DockerRuntime only supports mounting the workspace directory into the container. However, there are use cases where users need to mount additional directories from the host machine into the container, such as:

• Mounting read-only model directories (like pre-trained ML models)
• Accessing shared data directories
• Mounting temporary storage for downloads or generated content
• Using host machine's cached dependencies to improve performance

This is particularly useful when working with large datasets or models that already exist on the host machine and should be accessible from within the runtime environment.

Describe the UX or technical implementation you have in mind
I suggest implementing a new environment variable CUSTOM_VOLUMES that allows users to specify additional volume mounts in the following format:

CUSTOM_VOLUMES=/host/path1:/container/path1:rw,/host/path2:/container/path2:ro

Each mount specification consists of three parts:

• Host path: The path on the host machine
• Container path: Where to mount it inside the container
• Access mode: rw for read-write or ro for read-only

Multiple mounts would be separated by commas. The DockerRuntime would parse this environment variable and add these additional mounts when creating the container.

For example, users could run:

docker run -it -d \
    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.36-nikolaik \
    -e LOG_ALL_EVENTS=true \
    -e CUSTOM_VOLUMES="/opt/openhands/workspace:/workspace:rw,/mnt/data1:/data1:ro" \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v ~/.openhands-state:/.openhands-state \
    -p 3000:3000 \
    --add-host host.docker.internal:host-gateway \
    --name openhands-app \
    docker.all-hands.dev/all-hands-ai/openhands:0.36

Additional context

If you find this feature request or enhancement useful, make sure to add a 👍 to the issue

[xingyaoww]

Also, our current documentation of how to connect OpenHands to your local file system is overly complicated:
https://docs.all-hands.dev/modules/usage/runtimes/docker#connecting-to-your-filesystem

We need to specify both WORKSPACE_MOUNT_PATH and WORKSPACE_BASE for the mounting to work, but theoretically, we don't need all of these, since OpenHands docker can use the docker.sock to mount the workspace directly from the host machine into the runtime container.

@OpenHands, can you look at this issue, and figure out how current workspace mounting works with WORKSPACE_MOUNT_PATH and WORKSPACE_BASE (by reading the documentation), and come up with a fix that user can specify: RUNTIME_MOUNT=/my/host/dir:/workspace:rw and it will be equivalent as setting WORKSPACE_** env vars.

You should remove WORKSPACE_** env vars as deprecated and throw an error with instructions on how to fix it using the new RUNTIME_MOUNT env var. You should also update all the related documentation.

[openhands-ai]

I'm on it! xingyaoww can track my progress at all-hands.dev

[openhands-ai]

I've successfully addressed issue #8239 by simplifying the workspace mounting process in OpenHands Docker runtime. Here's a summary of the changes made:

Changes Implemented:

1. Added a new RUNTIME_MOUNT environment variable that replaces the multiple WORKSPACE_* variables with a single, more intuitive format: host_path:container_path[:mode]

2. Updated the configuration system:

   • Added a new runtime_mount parameter to AppConfig
   • Modified finalize_config to parse this parameter and set the old parameters for backward compatibility
   • Added deprecation warnings for the old WORKSPACE_* environment variables

3. Enhanced the Docker runtime to use the mount mode from RUNTIME_MOUNT, allowing users to specify read-only mounts with ro mode

4. Updated documentation in both English and Japanese to reflect the new simplified mounting process, with clear examples and migration guidance

5. Added comprehensive tests for the new functionality:

   • Tests for configuration parsing
   • Tests for mount mode extraction
   • Tests for backward compatibility

Pull Request:

I created PR #8241 (#8241) that fixes issue #8239. The PR includes all the necessary changes and has passed the tests I created.

Example Usage:

The new approach simplifies the user experience by allowing them to specify:

export RUNTIME_MOUNT=/path/to/host/dir:/workspace:rw

Instead of the previous more complex approach:

export WORKSPACE_BASE=/path/to/host/dir
export WORKSPACE_MOUNT_PATH=/path/to/host/dir
export WORKSPACE_MOUNT_PATH_IN_SANDBOX=/workspace

This change makes the Docker workspace mounting process more intuitive and consistent with standard Docker volume mounting syntax.

[hamiltop]

This change almost solves a problem I've had.

I would like to share datasets across sessions (including caching build dependencies and other things). But I don't want to mount the workspace.

The behavior of assuming the first volume is the workspace is problematic in other ways. This example from the documentation is completely broken:

# Read-only reference code example
export SANDBOX_VOLUMES=/path/to/reference/code:/data:ro

That causes any checkout to fail because /data becomes the workspace and it's readonly. Using the browser results in [Errno 30] Read-only file system

And with all the problems, the documentation doesn't even mention that the first mount will be used as the workspace. I had to dig into the code until I found this PR https://github.com/All-Hands-AI/OpenHands/blob/main/openhands/core/config/utils.py#L305 and followed the trail to this issue.

Can we please just have SANDBOX_VOLUMES only set the volumes for the docker level? There are many other ways we can specify the workspace, but it is incredibly unintuitive in the current form. I'm happy to help in any way I can.

[xingyaoww]

Thanks @hamiltop for the feedback 🙏

@OpenHands can you look at @hamiltop's comment in this github issue. Then, instead of treating the first mount as a "workspace" mount, if "/workspace" is not found in SANDBOX_VOLUMES, instead of forcing the first sandbox volume to be a workspace, we should NOT mount /workspace and use the default workspace path directly in sandbox /workspace.

[openhands-ai]

I'm on it! xingyaoww can track my progress at all-hands.dev

[openhands-ai]

I've successfully fixed issue #8239 in the OpenHands repository by modifying how workspace mounting works with SANDBOX_VOLUMES. The changes have been pushed to a new branch and a pull request has been created.