Skip to content

πŸ™Œ OpenHands: AI-Driven Development

Add vscode_port option to SandboxConfig (#8268)

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