[Bug]: Issue Report: OpenHands v0.40 runtime image 0.40-nikolaik does not start sandbox server, causing connection errors

[yourself-q]

Is there an existing issue for the same bug? (If one exists, thumbs up or comment on the issue instead).

• [ ] I have checked the existing issues.

Describe the bug and reproduction steps

Summary

I’m experiencing connection errors when running OpenHands v0.40 with the runtime image tagged 0.40-nikolaik. Specifically, the sandbox execution server fails to start, resulting in httpx.ConnectError when OpenHands tries to communicate with the runtime container.

Notably:

This setupworked before installing Docker Desktop. OpenHands v0.32 with runtime 0.32 works perfectly without errors. The problem only occurs with the v0.40 runtime image.

Steps to reproduce

1. Install Docker Desktop (Linux version is not officially supported, but this was done anyway).

2. Pull the problematic runtime image:

   docker pull docker.all-hands.dev/all-hands-ai/runtime:0.40-nikolaik

3. Run OpenHands v0.40 with this runtime image:

   docker run -it --rm --pull=always
   -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.40-nikolaik
   -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.40

4. If the container name conflict appears, remove the existing container (docker rm -f openhands-app) and retry.

5. OpenHands starts, but when it attempts to communicate with the sandbox runtime server, it fails with:

   httpx.ConnectError: [Errno 111] Connection refused

OpenHands Installation

Docker command in README

OpenHands Version

0.40

Operating System

None

Logs, Errors, Screenshots, and Additional Context

Logs snippet

httpx.ConnectError: [Errno 111] Connection refused

WARNING: docker_runtime.py:311 - [runtime ] Using host network mode. If you are using MacOS, please make sure you have the latest version of Docker Desktop and enabled host network feature: https://docs.docker.com/network/drivers/host/#docker-desktop

Additional findings

Running the runtime container standalone (runtime:0.40-nikolaik) results in just a Python REPL prompt, and no sandbox server is started. Inspecting the container’s filesystem reveals that the /app directory (where the server code should reside) is missing. In contrast, the runtime 0.32 image includes the server code and starts the sandbox server properly. Using runtime:0.32 with OpenHands v0.40 allows everything to work as expected, including sandbox executions.

Possible cause

The runtime:0.40-nikolaik Docker image appears to be missing necessary files and server startup configuration, likely due to a build or tagging issue. As a result, it only runs a Python interpreter without launching the sandbox server.

[trinity-cloud]

Having the same issue

[yourself-q]

Having the same issue

If you use 0.32, the error may not occur.

[Pusm]

same issue from v 0.41

[Pusm]

Has anyone been able to run version 0.41 stably on Windows Docker?

[Pusm]

or 0.40

[mamoodi]

I'm able to run OpenHands on Windows but with WSL and Docker Desktop. https://docs.all-hands.dev/usage/local-setup#windows

I just tried 0.41 and it's working. I usually pull the two docker images first because pull is slow in WSL:

docker pull docker.all-hands.dev/all-hands-ai/runtime:0.41-nikolaik
docker pull docker.all-hands.dev/all-hands-ai/openhands:0.41

Then I just run the docker command inside the WSL terminal while I have Docker Desktop running:

docker run -it --rm --pull=always \
    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.41-nikolaik \
    -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.41

[yourself-q]

I'm able to run OpenHands on Windows but with WSL and Docker Desktop. https://docs.all-hands.dev/usage/local-setup#windows

I just tried 0.41 and it's working. I usually pull the two docker images first because pull is slow in WSL:

docker pull docker.all-hands.dev/all-hands-ai/runtime:0.41-nikolaik
docker pull docker.all-hands.dev/all-hands-ai/openhands:0.41

Then I just run the docker command inside the WSL terminal while I have Docker Desktop running:

docker run -it --rm --pull=always \
    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.41-nikolaik \
    -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.41

That command might be a little interesting. In fact, when I used that command, I found a new error: httpx.ReadError: [Errno 104] Connection reset by peer. And I have a little solution to this problem. As I knew for a long time, the cause of this is the rewriting of the configuration by Docker Desktop. Now I'm going to do a little verification.

[Pusm]

Thank you, @yourself-q and @mamoodi. I've successfully resolved the issue by adapting your command for PowerShell. It is now running stably on my Windows + Docker Desktop environment.

For others who may encounter the same problem, here is the working PowerShell command that solved it:

The Solution (PowerShell) PowerShell

1. Pull the latest images

docker pull docker.all-hands.dev/all-hands-ai/runtime:0.41-nikolaik
docker pull docker.all-hands.dev/all-hands-ai/openhands:0.41

2. Run the container using the new images

docker run -it --rm --pull=always `
    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.41-nikolaik `
    -e LOG_ALL_EVENTS=true `
    -v /var/run/docker.sock:/var/run/docker.sock `
    -v "$HOME/.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.41

Analysis and Details As I mentioned in my previous comment, I was encountering a new error, httpx.ReadError: [Errno 104] Connection reset by peer, even with version 0.41.

The root cause appears to be related to how shell commands are interpreted on Windows, specifically regarding path expansion for volume mounts.

The Problem: The original command used -v~/.openhands-state:/.openhands-state. The tilde (~) character is not consistently expanded to the user's home directory in all Windows terminal environments (like it is in Linux/macOS). The Fix: The PowerShell version explicitly uses -v "$HOME/.openhands-state:/.openhands-state". Here, $HOME is PowerShell's environment variable for the user's home directory. This ensures that the full, correct path is passed to Docker. Hypothesis: My theory is that the unresolved or incorrectly mapped volume path was causing the sandbox runtime container to become unstable during its startup sequence, leading to the abrupt Connection reset by peer error. By providing a valid and explicit path with $HOME, the volume is mounted correctly, the container starts up stably, and the connection remains open as expected. For any other users on Windows, I strongly recommend using the PowerShell-native version of the command to avoid potential path interpretation issues.

I believe this fully resolves the problem I was facing. This issue can now be closed. Thank you again for the guidance!

[mamoodi]

Thanks @Pusm for your explanation and glad you got it working!

Just a side note, currently the only official way Windows is supported is through WSL. Lots of people have asked for alternatives so the team has been working on being able to run it without WSL and Docker Desktop. However, I'm not sure how far that is right now.

It is interesting that you got it working without WSL and only in powershell. The commands are only for running it within the WSL terminal so that's why it has the ~ character. In the near future, hopefully this will all be much smoother.

[Pusm]

Thanks @mamoodi . I wanted to share a updated version of reliable method I am using now to run OpenHands on Windows, as it might help others who are experiencing instability.

My Environment

• OS: Windows 11
• Setup: WSL 2 (installed using wsl --install with administrator privileges)
• Docker: Docker Desktop

The Problem

I sometimes encounter connection errors with Docker when starting a new session, especially after selecting a repository. The following process has made the startup process much more stable for me.

My Solution

All commands are run in PowerShell.

Step 1: One-Time Setup

First, manually pull the exact versions of the Docker images you need.

docker pull docker.all-hands.dev/all-hands-ai/runtime:0.42-nikolaik
docker pull docker.all-hands.dev/all-hands-ai/openhands:0.42

Step 2: Launch Script (For Every Session)

After the initial setup, use the following PowerShell script each time you want to start OpenHands.

This script does two things:

1. Clears old sessions: It removes the previous session folder to ensure a clean start.
2. Runs the container: It starts the OpenHands container using the pre-pulled images and specific settings.

# 1. Clean up old session folders
$sessionsPath = "$HOME\.openhands-state\sessions"
if (Test-Path -Path $sessionsPath) {
    Remove-Item -Path $sessionsPath -Recurse -Force
    Write-Host "Old session folder removed: $sessionsPath"
} else {
    Write-Host "Session folder not found, skipping removal."
}

# 2. Run the OpenHands container
docker run -it --rm `
    --pull=never `
    --name openhands-app `
    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.42-nikolaik `
    -e LOG_ALL_EVENTS=true `
    -e LLM_TEMPERATURE=0 `
    -e MAX_ITERATIONS=1000 `
    -v /var/run/docker.sock:/var/run/docker.sock `
    -v "$HOME\.openhands-state:/.openhands-state" `
    -p 3000:3000 `
    --add-host host.docker.internal:host-gateway `
    docker.all-hands.dev/all-hands-ai/openhands:0.42

I hope this detailed guide is helpful for others running OpenHands in a Windows + WSL environment!

[mamoodi]

Interesting. So you installed WSL but you ran the command in powershell. Then is WSL needed in this scenario?

[Pusm]

Update: I noticed that it's more stable to delete containers and session recordings each time.

I have confirmed that the following runs stably on Gemini 2.5 Pro/Flash, Sonnet 4, and o4-mini. (Gemini 2.5 is nice,but Gemini's output tends to be a bit rigid, and it can sometimes fall into loop errors, so I've adjusted the temperature setting.)

One-time

docker pull docker.all-hands.dev/all-hands-ai/runtime:0.42-nikolaik
docker pull docker.all-hands.dev/all-hands-ai/openhands:0.42

Every-time

# 0. Stop and remove all existing Docker containers
$allContainers = docker ps -aq
if ($allContainers) {
    Write-Host "Stopping and removing existing containers..."
    docker stop $allContainers
    docker rm $allContainers
    Write-Host "All containers stopped and removed."
} else {
    Write-Host "No containers to remove."
}

# 1. Remove old session folder
$sessionsPath = "$HOME\.openhands-state\sessions"
if (Test-Path -Path $sessionsPath) {
    Remove-Item -Path $sessionsPath -Recurse -Force
    Write-Host "Removed old session folder: $sessionsPath"
} else {
    Write-Host "Session folder does not exist, skipping removal."
}

# 2. Run the Docker container
docker run -it --rm `
    --pull=never `
    --name openhands-app `
    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.42-nikolaik `
    -e LOG_ALL_EVENTS=true `
    -e MAX_ITERATIONS=1000 `
    -e LLM_TEMPERATURE=0.2 `
    -e SANDBOX_TIMEOUT=600 `
    -v /var/run/docker.sock:/var/run/docker.sock `
    -v "$HOME\.openhands-state:/.openhands-state" `
    -p 3000:3000 `
    --add-host host.docker.internal:host-gateway `
    docker.all-hands.dev/all-hands-ai/openhands:0.42

Below is the version with AGENT_ENABLE_PROMPT_EXTENSIONS=0 added for DeepSeek R1.

One-time

docker pull docker.all-hands.dev/all-hands-ai/runtime:0.42-nikolaik
docker pull docker.all-hands.dev/all-hands-ai/openhands:0.42

Every-time

# 0. Stop and remove all existing Docker containers
$allContainers = docker ps -aq
if ($allContainers) {
    Write-Host "Stopping and removing existing containers..."
    docker stop $allContainers
    docker rm $allContainers
    Write-Host "All containers stopped and removed."
} else {
    Write-Host "No containers to remove."
}

# 1. Remove old session folder
$sessionsPath = "$HOME\.openhands-state\sessions"
if (Test-Path -Path $sessionsPath) {
    Remove-Item -Path $sessionsPath -Recurse -Force
    Write-Host "Removed old session folder: $sessionsPath"
} else {
    Write-Host "Session folder does not exist, skipping removal."
}

# 2. Run the Docker container
docker run -it --rm `
    --pull=never `
    --name openhands-app `
    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.42-nikolaik `
    -e LOG_ALL_EVENTS=true `
    -e MAX_ITERATIONS=1000 `
    -e SANDBOX_TIMEOUT=600 `
    -e AGENT_ENABLE_PROMPT_EXTENSIONS=0 `
    -v /var/run/docker.sock:/var/run/docker.sock `
    -v "$HOME\.openhands-state:/.openhands-state" `
    -p 3000:3000 `
    --add-host host.docker.internal:host-gateway `
    docker.all-hands.dev/all-hands-ai/openhands:0.42

[Pusm]

@mamoodi Thanks!

So for me, OpenHands actually didnt run stably without WSL 2.

And (as you know,) there are signs in my script that show WSL 2 is being used:

docker.sock mount: -v /var/run/docker.sock:/var/run/docker.sock This is a Linux-style socket path. You wouldn't typically use this if Docker was running natively on Windows. So, it pretty much confirms the Docker daemon is running in a Linux environment, thanks to WSL 2.

host.docker.internal with host-gateway: --add-host host.docker.internal:host-gateway This is the standard way for a container to reach the host PC, especially when Docker is running in a virtualized environment like WSL 2. If it were running natively on Windows, you usually wouldn't need this specific setup.

So, I figure that even though I'm running commands in PowerShell, WSL 2 is needed.

[github-actions[bot]]

This issue is stale because it has been open for 30 days with no activity. Remove stale label or comment or this will be closed in 7 days.

[github-actions[bot]]

This issue is stale because it has been open for 40 days with no activity. Remove the stale label or leave a comment, otherwise it will be closed in 10 days.

[github-actions[bot]]

This issue is stale because it has been open for 40 days with no activity. Remove the stale label or leave a comment, otherwise it will be closed in 10 days.

[github-actions[bot]]

This issue was automatically closed due to 50 days of inactivity. We do this to help keep the issues somewhat manageable and focus on active issues.