Document how to use custom sandbox container with Docker

[li-boxuan]

docs/modules/usage/how-to/custom-sandbox-guide.md only documents how to use a custom sandbox via Using the Development Workflow.

It doesn't document how to use a custom sandbox container via Docker. The correct usage should be:

docker run -it --pull=always \
    -e SANDBOX_BASE_CONTAINER_IMAGE=custom-image \
    -e LOG_ALL_EVENTS=true \
    -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.20

The support was added by #6039

Please document it accordingly.

[li-boxuan]

NOTE: this should wait until next release, i.e. the release after 0.19.0.

[amirshawn]

@li-boxuan I have tried litearally everything and haven't been able to make a custom image work. Do you have any tips? I've spent over 40 hours trying different way. I am probably way underestimating how many hours I've tried with no luck. I just tried exactly your way and same as always I get this error: 11:45:21 - openhands:ERROR: docker.py:137 - Python executable not found: [Errno 2] No such file or directory: 'docker' 11:45:21 - openhands:ERROR: session.py:116 - Error creating controller: [Errno 2] No such file or directory: 'docker' Traceback (most recent call last): File "/app/.venv/lib/python3.12/site-packages/docker/api/client.py", line 275, in _raise_for_status response.raise_for_status() File "/app/.venv/lib/python3.12/site-packages/requests/models.py", line 1024, in raise_for_status raise HTTPError(http_error_msg, response=self) requests.exceptions.HTTPError: 404 Client Error: Not Found for url: http+docker://localhost/v1.47/containers/openhands-runtime-8d8b74db5c674efaac7b4b6bd5197de4/json

I even tried what you mentioned with the stock base image and it failed. I'm on Mac OS.

I would appreciate the help if you ever figure out something!

[li-boxuan]

@amirshawn this feature is on main branch (unreleased yet), which is why I said the doc shall not be published before next release.

[mamoodi]

@li-boxuan I ran with main:

docker run -it --rm --pull=always \
    -e SANDBOX_BASE_CONTAINER_IMAGE="custom-image" \ 
    -e LOG_ALL_EVENTS=true \
    -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:main

and got an error:

================ DOCKER BUILD STARTED ================
20:00:55 - openhands:ERROR: docker.py:171 - Image build failed:
Command '['docker', 'buildx', 'build', '--progress=plain', '--build-arg=OPENHANDS_RUNTIME_VERSION=0.19.0', '--build-arg=OPENHANDS_RUNTIME_BUILD_TIME=2025-01-08T20:00:37.132238', '--tag=ghcr.io/all-hands-ai/runtime:oh_v0.19.0_veibzd9ds99nlmfe_ynit4mhuj2molx1y', '--load', '/tmp/tmpcw1jpovu']' returned non-zero exit status 1.
20:00:55 - openhands:ERROR: docker.py:172 - Command output:

20:00:55 - openhands:ERROR: session.py:116 - Error creating controller: Command '['docker', 'buildx', 'build', '--progress=plain', '--build-arg=OPENHANDS_RUNTIME_VERSION=0.19.0', '--build-arg=OPENHANDS_RUNTIME_BUILD_TIME=2025-01-08T20:00:37.132238', '--tag=ghcr.io/all-hands-ai/runtime:oh_v0.19.0_veibzd9ds99nlmfe_ynit4mhuj2molx1y', '--load', '/tmp/tmpcw1jpovu']' returned non-zero exit status 1.

This is the same error I got when running via development mode. Seems like something is broken? The development mode workflow with custom sandbox used to work but it no longer works. Likely some changes at some point changed the behavior.

[amirshawn]

Oh, that makes sense. I can't wait for it to finally work!

[li-boxuan]

The development mode workflow with custom sandbox used to work but it no longer works.

I kinda agree. It somehow works with some of my custom images but not others, even though they all used to work at some point. I tried to check out an old, verified release version but even that didn't work. My current believe is something non-deterministic inside the build logic broke it. For example, we might be pulling some dependencies in the code dynamically without specifying a fixed version. I didn't have a chance to check what has gone wrong there.

That being said, my error is different from yours @mamoodi . My error is a runtime error that says the browsing environment crashed; which I tend to believe is due to some change in some 3rd party dependency. Your error is build time error. Could you please open your Docker Desktop, goto Builds tab and inspect the build history?

[openhands-agent]

OpenHands started fixing the issue! You can monitor the progress here.

[openhands-agent]

An attempt was made to automatically fix this issue, but it was unsuccessful. A branch named 'openhands-fix-issue-6134' has been created with the attempted changes. You can view the branch here. Manual intervention may be required.

Additional details about the failure: While the AI agent has added documentation for using custom sandboxes via Docker, the issue thread reveals significant underlying technical problems that make this documentation premature and potentially misleading:

1. Multiple users are reporting that the custom sandbox functionality is not working properly, with consistent errors both in development and Docker modes
2. A core maintainer (@li-boxuan) acknowledged there are issues and mentioned this is unreleased functionality that should wait for the next release
3. There appears to be non-deterministic behavior where some custom images work and others don't, suggesting underlying implementation issues
4. The documentation addition alone doesn't address the fact that the feature itself appears to be broken or inconsistently functional

Simply documenting how to use a feature that is not working reliably does not resolve the issue. A proper resolution would require:

1. Fixing the underlying technical issues with custom sandbox functionality
2. Verifying the feature works consistently across different scenarios
3. Then adding accurate documentation that reflects the working implementation

The documentation changes themselves appear accurate to the intended usage, but documenting a broken feature is not a complete solution.

[li-boxuan]

@openhands-agent The functionality is already released. The fact that the feature itself seems non-functional, is, to my best knowledge, due to a setting on Mac OS (so, a user error).

[openhands-agent]

OpenHands started fixing the issue! You can monitor the progress here.

[openhands-agent]

OpenHands started fixing the issue! You can monitor the progress here.

[openhands-agent]

A potential fix has been generated and a draft PR #6257 has been created. Please review the changes.

[openhands-agent]

A potential fix has been generated and a draft PR #6258 has been created. Please review the changes.

[Tianhao-Peng]

@openhands-agent The functionality is already released. The fact that the feature itself seems non-functional, is, to my best knowledge, due to a setting on Mac OS (so, a user error).

@li-boxuan Hello, I have encountered this problem (Mac OS) with the newest version until now "8bf197df313e3d148221d4aaa418496adaeefae9". Could you please tell me more about the "user error" to fix it. Thank you

[mamoodi]

@Tianhao-Peng see this comment: https://github.com/All-Hands-AI/OpenHands/issues/6131#issuecomment-2585472110

Please let me know if this worked for you