Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.openhands.dev/llms.txt

Use this file to discover all available pages before exploring further.

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 AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server \
    -e AGENT_SERVER_IMAGE_TAG=1.19.1-python \
    -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.openhands.dev/openhands/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

​
User Skills Not Loading in Docker

Description When running OpenHands via Docker, custom skills placed in ~/.openhands/skills/ or ~/.agents/skills/ on the host machine are not loaded. The skill loader logs show 'user': 0. Resolution The agent-server container cannot see your host filesystem by default. Mount your local skills directory into the sandbox using the SANDBOX_VOLUMES environment variable: 
-e SANDBOX_VOLUMES="$HOME/.agents/skills:/home/openhands/.agents/skills:ro"
Mount into ~/.agents/skills inside the container, not ~/.openhands/skills. The latter would overwrite the public skills cache and prevent built-in skills from loading.
See User Skills When Running OpenHands on Your Own for the full Docker command.

​
GitHub Organization Rename Issues

Description After the GitHub organization rename from All-Hands-AI to OpenHands, you may encounter issues with git remotes, Docker images, or broken links. Resolution
  • Update your git remote URL: 
    # Check current remote
git remote get-url origin

# Update SSH remote
git remote set-url origin git@github.com:OpenHands/OpenHands.git

# Or update HTTPS remote
git remote set-url origin https://github.com/OpenHands/OpenHands.git
  • Update Docker image references from ghcr.io/all-hands-ai/ to ghcr.io/openhands/
  • Find and update any hardcoded references: 
    git grep -i "all-hands-ai"
git grep -i "ghcr.io/all-hands-ai"