Document Linux Docker user mapping

[koriyoshi2041]

Why

Linux users running rootful Docker Engine can hit write permission errors on the bind-mounted ~/.openhands directory because the container runs as the baked-in openhands user while the host directory is owned by the host user. This was reported in OpenHands/OpenHands#14882 and confirmed as a docs gap.

Summary

• Add a Linux rootful Docker Engine note to the Docker Sandbox README section.
• Show the same docker run command with --user "$(id -u):$(id -g)" so the mounted OpenHands config directory remains writable.

Issue Number

References OpenHands/OpenHands#14882.

How to Test

• git diff --check -- README.md

Video/Screenshots

Docs-only change.

Type

• Docs / chore

Notes

Kept the existing macOS/Linux command unchanged and added the Linux-specific variant only for the rootful Docker Engine permission case.

[vercel]

@koriyoshi2041 is attempting to deploy a commit to the openhands Team on Vercel.

A member of the Team first needs to authorize it.

[mysteryx93]

There's another permission issue to deal with, ensuring the current user is in the proper group. I think that's already in the docs, but both permission issues could be clearly put together.

[mysteryx93]

Now, if I want to use Docker Compose instead, it gets a bit more problematic. I cannot use "$(id -u):$(id -g)", only environment variables. So either I export UID and GID into shell environment variables, hardcode the values in the file, or manually define them in a .env file.

Why is it running as a different user to begin with? Is there a cleaner solution?

services:
  openhands:
    image: ghcr.io/openhands/agent-canvas:latest
    user: "${UID}:${GID}"
    ports:
      - "8000:8000"
    volumes:
      - "${HOME}/.openhands:/home/openhands/.openhands"
      - "${HOME}/projects:/projects"
    stdin_open: true
    tty: true

I think the documentation could include Docker Compose as well.

Should the home page instructions have any change? It's only partial instructions that will fail with permission issues. Have to dig deeper into the documentation to know that Docker Desktop app isn't strictly required; probably after seeing the failed permissions problem. That cycle of digging-after-error could be avoided.

What about the image version, should a fixed version be set in the documentation, that gets outdated pretty quick, or set it as 'latest'?

[koriyoshi2041]

Thanks, that Compose case is a good catch. I added a short rootful-Linux Compose example in the README using HOST_UID / HOST_GID instead of UID, since UID is read-only in some shells. I kept the image tag aligned with the existing quickstart example for now so this PR stays scoped to the permissions path.

[VascoSch92]

Hey @koriyoshi2041 and @mysteryx93

thank you very much for the PR and the review of the PR.

@mysteryx93 Could you confirm that the last commit is adressing your point?

After that I think we are good to go.

[mysteryx93]

${PROJECTS_PATH} doesn't work for me. Also since Linux formally added ~/Projects, I'm pretty sure we should use that instead of ~/projects. But should be consistent about that across the docs.

As for exporting environment variable, it's honestly very cumbersome. Even if I add that into a script, it's only valid within that script and must be re-defined when calling docker compose down.

Setting user: 1000:1000 might honestly be the cleanest solution, calling id-u and id-g only once before configuring. Docker Compose file is server-specific code anyway, often with custom locations.

This works for me.

services:
  openhands:
    image: ghcr.io/openhands/agent-canvas:latest
    user: 1000:1000 # id -u:id -g
    ports:
      - "8000:8000"
    volumes:
      - "${HOME}/.openhands:/home/openhands/.openhands"
      - "${HOME}/Projects:/projects"

[koriyoshi2041]

Thanks, that makes sense. I pushed d5bb08b to simplify the Compose example: it no longer requires exported UID/GID variables, and instead shows a direct user: "1000:1000" value with a note to replace it with id -u:id -g. I also changed the Compose mount to a concrete /Users/parafee41/projects example so it does not depend on PROJECTS_PATH being set.\n\nLocal check: git diff --check -- README.md.

[mysteryx93]

${HOME} works perfectly fine, should use that. Plus you use it for one mount path but not for the other?

[koriyoshi2041]

You are right; I worded my last reply poorly. The pushed head uses ${HOME} consistently in the Compose example now:

volumes:
  - "${HOME}/.openhands:/home/openhands/.openhands"
  - "${HOME}/projects:/projects"

I kept the default aligned with the existing README PROJECTS_PATH="$HOME/projects" setup, so this PR does not change the docs-wide project directory convention.

[mysteryx93]

ok looking much better.

Could definitely have another PR for changing "projects" to "Projects" (otherwise you end up with both folders on your computers which is weird and confusing), and for changing fixed old version to latest.