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.

​
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