From 3361de1585ea29d3ea02b5931c6562475e4b14ef Mon Sep 17 00:00:00 2001 From: "M.Y. Hadef" Date: Mon, 7 Sep 2026 19:39:13 +0200 Subject: [PATCH 1/3] docs: note Windows WinNAT port reservations breaking SSH tunnels Added troubleshooting steps for SSH port forwarding issues on Windows, including commands to check and release reserved ports. --- enterprise/troubleshooting.mdx | 41 ++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/enterprise/troubleshooting.mdx b/enterprise/troubleshooting.mdx index ed46e2276..c34d83108 100644 --- a/enterprise/troubleshooting.mdx +++ b/enterprise/troubleshooting.mdx @@ -212,3 +212,44 @@ short investigation: Send VM installation logs to your own observability platform. + +### SSH port forwarding fails on Windows with "bind: Permission denied" + +When you access the UI on a remote host, the browser connects to the sandbox on a +randomly assigned high port, so that port has to be forwarded as well: + +```bash +ssh -N -L 3100:127.0.0.1:3100 -L 41549:127.0.0.1:41549 user@host +``` + +On Windows this can fail with: + +``` +bind [127.0.0.1]:41549: Permission denied +channel_setup_fwd_listener_tcpip: cannot listen to port: 41549 +``` + +WinNAT, Hyper-V and WSL dynamically reserve blocks of ports inside the same +32768–60999 range Docker allocates from, and no process can bind inside them. +The port looks free but cannot be used. + +To list the reserved ranges, in an Administrator PowerShell: + +```powershell +netsh interface ipv4 show excludedportrange protocol=tcp +``` + +Dynamic reservations do not always appear in this table, so a port outside every +listed range can still be blocked. + +To release them, in an Administrator PowerShell: + +```powershell +net stop winnat +``` + +Start the SSH tunnel, then restore normal networking: + +```powershell +net start winnat +``` From 56cc489b2ef639cd9a90a7664fd5deb53820eb68 Mon Sep 17 00:00:00 2001 From: "M. Yacine Hadef" Date: Mon, 12 Oct 2026 09:14:39 +0200 Subject: [PATCH 2/3] Remove SSH port forwarding troubleshooting section Removed section about SSH port forwarding issues on Windows, including troubleshooting steps and commands. --- enterprise/troubleshooting.mdx | 41 ---------------------------------- 1 file changed, 41 deletions(-) diff --git a/enterprise/troubleshooting.mdx b/enterprise/troubleshooting.mdx index c34d83108..ed46e2276 100644 --- a/enterprise/troubleshooting.mdx +++ b/enterprise/troubleshooting.mdx @@ -212,44 +212,3 @@ short investigation: Send VM installation logs to your own observability platform. - -### SSH port forwarding fails on Windows with "bind: Permission denied" - -When you access the UI on a remote host, the browser connects to the sandbox on a -randomly assigned high port, so that port has to be forwarded as well: - -```bash -ssh -N -L 3100:127.0.0.1:3100 -L 41549:127.0.0.1:41549 user@host -``` - -On Windows this can fail with: - -``` -bind [127.0.0.1]:41549: Permission denied -channel_setup_fwd_listener_tcpip: cannot listen to port: 41549 -``` - -WinNAT, Hyper-V and WSL dynamically reserve blocks of ports inside the same -32768–60999 range Docker allocates from, and no process can bind inside them. -The port looks free but cannot be used. - -To list the reserved ranges, in an Administrator PowerShell: - -```powershell -netsh interface ipv4 show excludedportrange protocol=tcp -``` - -Dynamic reservations do not always appear in this table, so a port outside every -listed range can still be blocked. - -To release them, in an Administrator PowerShell: - -```powershell -net stop winnat -``` - -Start the SSH tunnel, then restore normal networking: - -```powershell -net start winnat -``` From c41620f3beae598a00275fb5dc08686d6f7d70cf Mon Sep 17 00:00:00 2001 From: Admin Date: Mon, 12 Oct 2026 09:35:58 +0200 Subject: [PATCH 3/3] docs: add Windows WinNAT SSH tunnel troubleshooting entry --- .../usage/troubleshooting/troubleshooting.mdx | 33 +++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/openhands/usage/troubleshooting/troubleshooting.mdx b/openhands/usage/troubleshooting/troubleshooting.mdx index 8b586d875..a35cdfd03 100644 --- a/openhands/usage/troubleshooting/troubleshooting.mdx +++ b/openhands/usage/troubleshooting/troubleshooting.mdx @@ -70,6 +70,39 @@ way forbidden by its access permissions.")` is encountered. Restart-Service -Name "winnat" ``` +### SSH port forwarding fails with "bind: Permission denied" + +**Description** + +When reaching OpenHands over an SSH tunnel, the browser connects directly to the sandbox's randomly assigned host port, so that port must be forwarded alongside the app port: + +```bash theme={null} +ssh -N -L :127.0.0.1: -L 41549:127.0.0.1:41549 user@host +``` + +On Windows the forward itself can fail: + +``` +bind [127.0.0.1]:41549: Permission denied +channel_setup_fwd_listener_tcpip: cannot listen to port: 41549 +``` + +WinNAT, Hyper-V and WSL dynamically reserve blocks of ports inside the same range the sandbox allocates from. These dynamic reservations do not reliably appear in the exclusion table, so a port outside every listed range can still be unbindable: + +```powershell theme={null} +netsh interface ipv4 show excludedportrange protocol=tcp +``` + +**Resolution** + +Stop WinNAT in PowerShell as Administrator, start the SSH tunnel in another window, then restart WinNAT. The already-open tunnel survives: + +```powershell theme={null} +net stop winnat +# start the SSH tunnel in another window, then: +net start winnat +``` + ### Unable to access VS Code tab via local IP **Description**