OpenHands only supports Windows via WSL. Please be sure to run all commands inside your WSL terminal.

​
Launch docker client failed

Description When running OpenHands, the following error is seen: 
Launch docker client failed. Please make sure you have installed docker and started docker desktop/daemon.
Resolution Try these in order:
  • Confirm docker is running on your system. You should be able to run docker ps in the terminal successfully.
  • If using Docker Desktop, ensure Settings > Advanced > Allow the default Docker socket to be used is enabled.
  • Depending on your configuration you may need Settings > Resources > Network > Enable host networking enabled in Docker Desktop.
  • Reinstall Docker Desktop.

​
Permission Error

Description On initial prompt, an error is seen with Permission Denied or PermissionError. Resolution
  • Check if the ~/.openhands is owned by root. If so, you can:
    • Change the directory’s ownership: sudo chown <user>:<user> ~/.openhands.
    • or update permissions on the directory: sudo chmod 777 ~/.openhands
    • or delete it if you don’t need previous data. OpenHands will recreate it. You’ll need to re-enter LLM settings.
  • If mounting a local directory, ensure your WORKSPACE_BASE has the necessary permissions for the user running OpenHands.

​
On Linux, Getting ConnectTimeout Error

Description When running on Linux, you might run into the error ERROR:root:<class 'httpx.ConnectTimeout'>: timed out. Resolution If you installed Docker from your distribution’s package repository (e.g., docker.io on Debian/Ubuntu), be aware that these packages can sometimes be outdated or include changes that cause compatibility issues. try reinstalling Docker using the official instructions to ensure you are running a compatible version. If that does not solve the issue, try incrementally adding the following parameters to the docker run command:
  • --network host
  • -e SANDBOX_USE_HOST_NETWORK=true
  • -e DOCKER_HOST_ADDR=127.0.0.1

​
Internal Server Error. Ports are not available

Description When running on Windows, the error Internal Server Error ("ports are not available: exposing port TCP ...: bind: An attempt was made to access a socket in a way forbidden by its access permissions.") is encountered. Resolution
  • Run the following command in PowerShell, as Administrator to reset the NAT service and release the ports:
Restart-Service -Name "winnat"

​
Unable to access VS Code tab via local IP

Description When accessing OpenHands through a non-localhost URL (such as a LAN IP address), the VS Code tab shows a “Forbidden” error, while other parts of the UI work fine. Resolution This happens because VS Code runs on a random high port that may not be exposed or accessible from other machines. To fix this:
  1. Set a specific port for VS Code using the SANDBOX_VSCODE_PORT environment variable: 
    docker run -it --rm \
    -e SANDBOX_VSCODE_PORT=41234 \
    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:latest \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v ~/.openhands:/.openhands \
    -p 3000:3000 \
    -p 41234:41234 \
    --add-host host.docker.internal:host-gateway \
    --name openhands-app \
    docker.all-hands.dev/all-hands-ai/openhands:latest
    Note: If you used OpenHands before version 0.44, you may want to run mv ~/.openhands-state ~/.openhands to migrate your conversation history to the new location.
  2. Make sure to expose the same port with -p 41234:41234 in your Docker command.
  3. If running with the development workflow, you can set this in your config.toml file: 
    [sandbox]
vscode_port = 41234