From 421b8e948d80f661a26f8a67729a12ca7526ab1b Mon Sep 17 00:00:00 2001
From: Xingyao Wang <xingyao@all-hands.dev>
Date: Mon, 5 May 2025 10:11:34 +0800
Subject: [PATCH] Add vscode_port option to SandboxConfig (#8268)

Co-authored-by: openhands <openhands@all-hands.dev>
---
 config.template.toml                          |  4 +++
 .../usage/troubleshooting/troubleshooting.md  | 32 +++++++++++++++++++
 openhands/core/config/sandbox_config.py       |  3 ++
 .../runtime/impl/docker/docker_runtime.py     |  6 +++-
 4 files changed, 44 insertions(+), 1 deletion(-)

diff --git a/config.template.toml b/config.template.toml
index f924a66a32..8d55055ca5 100644
--- a/config.template.toml
+++ b/config.template.toml
@@ -316,6 +316,10 @@ llm_config = 'gpt3'
 # Additional Docker runtime kwargs
 #docker_runtime_kwargs = {}
 
+# Specific port to use for VSCode. If not set, a random port will be chosen.
+# Useful when deploying OpenHands in a remote machine where you need to expose a specific port.
+#vscode_port = 41234
+
 #################################### Security ###################################
 # Configuration for security features
 ##############################################################################
diff --git a/docs/modules/usage/troubleshooting/troubleshooting.md b/docs/modules/usage/troubleshooting/troubleshooting.md
index 70232db8f3..b879e0c548 100644
--- a/docs/modules/usage/troubleshooting/troubleshooting.md
+++ b/docs/modules/usage/troubleshooting/troubleshooting.md
@@ -4,6 +4,38 @@
 OpenHands only supports Windows via WSL. Please be sure to run all commands inside your WSL terminal.
 :::
 
+### 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:
+   ```bash
+   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-state:/.openhands-state \
+       -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
+   ```
+
+2. Make sure to expose the same port with `-p 41234:41234` in your Docker command.
+
+3. Alternatively, you can set this in your `config.toml` file:
+   ```toml
+   [sandbox]
+   vscode_port = 41234
+   ```
+
 ### Launch docker client failed
 
 **Description**
diff --git a/openhands/core/config/sandbox_config.py b/openhands/core/config/sandbox_config.py
index ae81cc5d15..a335579e9d 100644
--- a/openhands/core/config/sandbox_config.py
+++ b/openhands/core/config/sandbox_config.py
@@ -39,6 +39,8 @@ class SandboxConfig(BaseModel):
         docker_runtime_kwargs: Additional keyword arguments to pass to the Docker runtime when running containers.
             This should be a JSON string that will be parsed into a dictionary.
         trusted_dirs: List of directories that can be trusted to run the OpenHands CLI.
+        vscode_port: The port to use for VSCode. If None, a random port will be chosen.
+            This is useful when deploying OpenHands in a remote machine where you need to expose a specific port.
     """
 
     remote_runtime_api_url: str | None = Field(default='http://localhost:8000')
@@ -77,6 +79,7 @@ class SandboxConfig(BaseModel):
     docker_runtime_kwargs: dict | None = Field(default=None)
     selected_repo: str | None = Field(default=None)
     trusted_dirs: list[str] = Field(default_factory=list)
+    vscode_port: int | None = Field(default=None)
 
     model_config = {'extra': 'forbid'}
 
diff --git a/openhands/runtime/impl/docker/docker_runtime.py b/openhands/runtime/impl/docker/docker_runtime.py
index aa71637106..c0fc01a6f5 100644
--- a/openhands/runtime/impl/docker/docker_runtime.py
+++ b/openhands/runtime/impl/docker/docker_runtime.py
@@ -212,7 +212,11 @@ class DockerRuntime(ActionExecutionClient):
         self.send_status_message('STATUS$PREPARING_CONTAINER')
         self._host_port = self._find_available_port(EXECUTION_SERVER_PORT_RANGE)
         self._container_port = self._host_port
-        self._vscode_port = self._find_available_port(VSCODE_PORT_RANGE)
+        # Use the configured vscode_port if provided, otherwise find an available port
+        self._vscode_port = (
+            self.config.sandbox.vscode_port
+            or self._find_available_port(VSCODE_PORT_RANGE)
+        )
         self._app_ports = [
             self._find_available_port(APP_PORT_RANGE_1),
             self._find_available_port(APP_PORT_RANGE_2),