Add vscode_port option to SandboxConfig (#8268)

Co-authored-by: openhands <openhands@all-hands.dev>

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
 ##############################################################################

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**

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'}
 

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),