π OpenHands: AI-Driven Development
feat: add host network support for V1 DockerSandboxService (#12445)
MkDev11c483c80a3c33
diff --git a/openhands/app_server/sandbox/docker_sandbox_service.py b/openhands/app_server/sandbox/docker_sandbox_service.pyindex f9f7dfc80b..1114fde577 100644--- a/openhands/app_server/sandbox/docker_sandbox_service.py+++ b/openhands/app_server/sandbox/docker_sandbox_service.py@@ -84,6 +84,7 @@ class DockerSandboxService(SandboxService):extra_hosts: dict[str, str] = field(default_factory=dict)docker_client: docker.DockerClient = field(default_factory=get_docker_client)startup_grace_seconds: int = STARTUP_GRACE_SECONDS+ use_host_network: bool = Falsedef _find_unused_port(self) -> int:"""Find an unused port on the host machine."""@@ -140,36 +141,61 @@ class DockerSandboxService(SandboxService):env = self._get_container_env_vars(container)session_api_key = env.get(SESSION_API_KEY_VARIABLE)- # Get the first exposed port mapping+ # Get the exposed port mappingsexposed_urls = []- port_bindings = container.attrs.get('NetworkSettings', {}).get('Ports', {})- if port_bindings:- for container_port, host_bindings in port_bindings.items():- if host_bindings:- host_port = host_bindings[0]['HostPort']- exposed_port = next(- (- exposed_port- for exposed_port in self.exposed_ports- if container_port- == f'{exposed_port.container_port}/tcp'- ),- None,++ # Check if container is using host network mode+ network_mode = container.attrs.get('HostConfig', {}).get('NetworkMode', '')+ is_host_network = network_mode == 'host'++ if is_host_network:+ # Host network mode: container ports are directly accessible on host+ for exposed_port in self.exposed_ports:+ host_port = exposed_port.container_port+ url = self.container_url_pattern.format(port=host_port)++ # VSCode URLs require the api_key and working dir+ if exposed_port.name == VSCODE:+ url += f'/?tkn={session_api_key}&folder={container.attrs["Config"]["WorkingDir"]}'++ exposed_urls.append(+ ExposedUrl(+ name=exposed_port.name,+ url=url,+ port=host_port,)- if exposed_port:- url = self.container_url_pattern.format(port=host_port)-- # VSCode URLs require the api_key and working dir- if exposed_port.name == VSCODE:- url += f'/?tkn={session_api_key}&folder={container.attrs["Config"]["WorkingDir"]}'-- exposed_urls.append(- ExposedUrl(- name=exposed_port.name,- url=url,- port=host_port,- )+ )+ else:+ # Bridge network mode: use port bindings+ port_bindings = container.attrs.get('NetworkSettings', {}).get(+ 'Ports', {}+ )+ if port_bindings:+ for container_port, host_bindings in port_bindings.items():+ if host_bindings:+ host_port = int(host_bindings[0]['HostPort'])+ matching_port = next(+ (+ ep+ for ep in self.exposed_ports+ if container_port == f'{ep.container_port}/tcp'+ ),+ None,)+ if matching_port:+ url = self.container_url_pattern.format(port=host_port)++ # VSCode URLs require the api_key and working dir+ if matching_port.name == VSCODE:+ url += f'/?tkn={session_api_key}&folder={container.attrs["Config"]["WorkingDir"]}'++ exposed_urls.append(+ ExposedUrl(+ name=matching_port.name,+ url=url,+ port=host_port,+ )+ )return SandboxInfo(id=container.name,@@ -300,6 +326,15 @@ class DockerSandboxService(SandboxService):self, sandbox_spec_id: str | None = None, sandbox_id: str | None = None) -> SandboxInfo:"""Start a new sandbox."""+ # Warn about port collision risk when using host network mode with multiple sandboxes+ if self.use_host_network and self.max_num_sandboxes > 1:+ _logger.warning(+ 'Host network mode is enabled with max_num_sandboxes > 1. '+ 'Multiple sandboxes will attempt to bind to the same ports, '+ 'which may cause port collision errors. Consider setting '+ 'max_num_sandboxes=1 when using host network mode.'+ )+# Enforce sandbox limits by cleaning up old sandboxesawait self.pause_old_sandboxes(self.max_num_sandboxes - 1)@@ -335,12 +370,20 @@ class DockerSandboxService(SandboxService):env_vars[ALLOW_CORS_ORIGINS_VARIABLE] = self.web_url# Prepare port mappings and add port environment variables- port_mappings = {}- for exposed_port in self.exposed_ports:- host_port = self._find_unused_port()- port_mappings[exposed_port.container_port] = host_port- # Add port as environment variable- env_vars[exposed_port.name] = str(host_port)+ # When using host network, container ports are directly accessible on the host+ # so we use the container ports directly instead of mapping to random host ports+ port_mappings: dict[int, int] | None = None+ if self.use_host_network:+ # Host network mode: container ports are directly accessible+ for exposed_port in self.exposed_ports:+ env_vars[exposed_port.name] = str(exposed_port.container_port)+ else:+ # Bridge network mode: map container ports to random host ports+ port_mappings = {}+ for exposed_port in self.exposed_ports:+ host_port = self._find_unused_port()+ port_mappings[exposed_port.container_port] = host_port+ env_vars[exposed_port.name] = str(host_port)# Prepare labelslabels = {@@ -356,6 +399,12 @@ class DockerSandboxService(SandboxService):for mount in self.mounts}+ # Determine network mode+ network_mode = 'host' if self.use_host_network else None++ if self.use_host_network:+ _logger.info(f'Starting sandbox {container_name} with host network mode')+try:# Create and start the containercontainer = self.docker_client.containers.run( # type: ignore[call-overload]@@ -374,7 +423,12 @@ class DockerSandboxService(SandboxService):init=True,# Allow agent-server containers to resolve host.docker.internal# and other custom hostnames for LAN deployments- extra_hosts=self.extra_hosts if self.extra_hosts else None,+ # Note: extra_hosts is not needed with host network mode+ extra_hosts=self.extra_hosts+ if self.extra_hosts and not self.use_host_network+ else None,+ # Network mode: 'host' for host networking, None for default bridge+ network_mode=network_mode,)sandbox_info = await self._container_to_sandbox_info(container)@@ -526,6 +580,21 @@ class DockerSandboxServiceInjector(SandboxServiceInjector):'before it is considered an error'),)+ use_host_network: bool = Field(+ default=os.getenv('SANDBOX_USE_HOST_NETWORK', '').lower()+ in (+ 'true',+ '1',+ 'yes',+ ),+ description=(+ 'Whether to use host networking mode for sandbox containers. '+ 'When enabled, containers share the host network namespace, '+ 'making all container ports directly accessible on the host. '+ 'This is useful for reverse proxy setups where dynamic port mapping '+ 'is problematic. Configure via OH_SANDBOX_USE_HOST_NETWORK environment variable.'+ ),+ )async def inject(self, state: InjectorState, request: Request | None = None@@ -558,4 +627,5 @@ class DockerSandboxServiceInjector(SandboxServiceInjector):web_url=web_url,extra_hosts=self.extra_hosts,startup_grace_seconds=self.startup_grace_seconds,+ use_host_network=self.use_host_network,)diff --git a/tests/unit/app_server/test_docker_sandbox_service.py b/tests/unit/app_server/test_docker_sandbox_service.pyindex d62c90a83e..b951167d02 100644--- a/tests/unit/app_server/test_docker_sandbox_service.py+++ b/tests/unit/app_server/test_docker_sandbox_service.py@@ -1181,6 +1181,24 @@ class TestDockerSandboxServiceInjector:assert injector.host_port == 4000assert injector.container_url_pattern == 'http://192.168.1.100:{port}'+ def test_use_host_network_default_value(self):+ """Test that use_host_network field defaults to False."""+ from openhands.app_server.sandbox.docker_sandbox_service import (+ DockerSandboxServiceInjector,+ )++ injector = DockerSandboxServiceInjector()+ assert injector.use_host_network is False++ def test_use_host_network_can_be_enabled(self):+ """Test that use_host_network field can be set to True."""+ from openhands.app_server.sandbox.docker_sandbox_service import (+ DockerSandboxServiceInjector,+ )++ injector = DockerSandboxServiceInjector(use_host_network=True)+ assert injector.use_host_network is True+class TestDockerSandboxServiceInjectorFromEnv:"""Test cases for DockerSandboxServiceInjector environment variable configuration."""@@ -1246,3 +1264,280 @@ class TestDockerSandboxServiceInjectorFromEnv:assert config.sandbox is not Noneassert config.sandbox.host_port == 4000assert config.sandbox.container_url_pattern == 'http://192.168.1.100:{port}'+++class TestDockerSandboxServiceHostNetwork:+ """Test cases for DockerSandboxService with host network mode."""++ @pytest.fixture+ def service_with_host_network(+ self, mock_sandbox_spec_service, mock_httpx_client, mock_docker_client+ ):+ """Create DockerSandboxService instance with host network enabled."""+ return DockerSandboxService(+ sandbox_spec_service=mock_sandbox_spec_service,+ container_name_prefix='oh-test-',+ host_port=3000,+ container_url_pattern='http://localhost:{port}',+ mounts=[],+ exposed_ports=[+ ExposedPort(+ name=AGENT_SERVER, description='Agent server', container_port=8000+ ),+ ExposedPort(+ name=VSCODE, description='VSCode server', container_port=8001+ ),+ ],+ health_check_path='/health',+ httpx_client=mock_httpx_client,+ max_num_sandboxes=3,+ docker_client=mock_docker_client,+ use_host_network=True,+ )++ @pytest.fixture+ def mock_host_network_container(self):+ """Create a mock container running with host network mode."""+ container = MagicMock()+ container.name = 'oh-test-abc123'+ container.status = 'running'+ container.image.tags = ['spec456']+ container.attrs = {+ 'Created': '2024-01-15T10:30:00.000000000Z',+ 'Config': {+ 'Env': [+ 'OH_SESSION_API_KEYS_0=session_key_123',+ 'OTHER_VAR=other_value',+ ],+ 'WorkingDir': '/workspace',+ },+ 'HostConfig': {+ 'NetworkMode': 'host',+ },+ 'NetworkSettings': {+ 'Ports': None,+ },+ }+ return container++ @patch('openhands.app_server.sandbox.docker_sandbox_service.base62.encodebytes')+ @patch('os.urandom')+ async def test_start_sandbox_with_host_network(+ self, mock_urandom, mock_encodebytes, service_with_host_network+ ):+ """Test starting sandbox with host network mode."""+ mock_urandom.side_effect = [b'container_id', b'session_key']+ mock_encodebytes.side_effect = ['test_container_id', 'test_session_key']++ mock_container = MagicMock()+ mock_container.name = 'oh-test-test_container_id'+ mock_container.status = 'running'+ mock_container.image.tags = ['test-image:latest']+ mock_container.attrs = {+ 'Created': '2024-01-15T10:30:00.000000000Z',+ 'Config': {+ 'Env': [+ 'OH_SESSION_API_KEYS_0=test_session_key',+ 'TEST_VAR=test_value',+ ],+ 'WorkingDir': '/workspace',+ },+ 'HostConfig': {'NetworkMode': 'host'},+ 'NetworkSettings': {'Ports': None},+ }++ service_with_host_network.docker_client.containers.run.return_value = (+ mock_container+ )++ with patch.object(+ service_with_host_network, 'pause_old_sandboxes', return_value=[]+ ):+ result = await service_with_host_network.start_sandbox()++ assert result is not None+ assert result.id == 'oh-test-test_container_id'++ call_args = service_with_host_network.docker_client.containers.run.call_args+ assert call_args[1]['network_mode'] == 'host'+ assert call_args[1]['ports'] is None+ assert call_args[1]['extra_hosts'] is None++ @patch('openhands.app_server.sandbox.docker_sandbox_service.base62.encodebytes')+ @patch('os.urandom')+ async def test_start_sandbox_host_network_uses_container_ports(+ self, mock_urandom, mock_encodebytes, service_with_host_network+ ):+ """Test that host network mode uses container ports directly in env vars."""+ mock_urandom.side_effect = [b'container_id', b'session_key']+ mock_encodebytes.side_effect = ['test_container_id', 'test_session_key']++ mock_container = MagicMock()+ mock_container.name = 'oh-test-test_container_id'+ mock_container.status = 'running'+ mock_container.image.tags = ['test-image:latest']+ mock_container.attrs = {+ 'Created': '2024-01-15T10:30:00.000000000Z',+ 'Config': {+ 'Env': ['OH_SESSION_API_KEYS_0=test_session_key'],+ 'WorkingDir': '/workspace',+ },+ 'HostConfig': {'NetworkMode': 'host'},+ 'NetworkSettings': {'Ports': None},+ }++ service_with_host_network.docker_client.containers.run.return_value = (+ mock_container+ )++ with patch.object(+ service_with_host_network, 'pause_old_sandboxes', return_value=[]+ ):+ await service_with_host_network.start_sandbox()++ call_args = service_with_host_network.docker_client.containers.run.call_args+ env_vars = call_args[1]['environment']+ assert env_vars[AGENT_SERVER] == '8000'+ assert env_vars[VSCODE] == '8001'++ async def test_container_to_sandbox_info_host_network(+ self, service_with_host_network, mock_host_network_container+ ):+ """Test conversion of host network container to SandboxInfo."""+ result = await service_with_host_network._container_to_sandbox_info(+ mock_host_network_container+ )++ assert result is not None+ assert result.id == 'oh-test-abc123'+ assert result.status == SandboxStatus.RUNNING+ assert result.session_api_key == 'session_key_123'+ assert len(result.exposed_urls) == 2++ agent_url = next(url for url in result.exposed_urls if url.name == AGENT_SERVER)+ assert agent_url.url == 'http://localhost:8000'+ assert agent_url.port == 8000++ vscode_url = next(url for url in result.exposed_urls if url.name == VSCODE)+ assert (+ vscode_url.url+ == 'http://localhost:8001/?tkn=session_key_123&folder=/workspace'+ )+ assert vscode_url.port == 8001++ @patch('openhands.app_server.sandbox.docker_sandbox_service._logger')+ @patch('openhands.app_server.sandbox.docker_sandbox_service.base62.encodebytes')+ @patch('os.urandom')+ async def test_start_sandbox_host_network_warns_multiple_sandboxes(+ self,+ mock_urandom,+ mock_encodebytes,+ mock_logger,+ mock_sandbox_spec_service,+ mock_httpx_client,+ mock_docker_client,+ ):+ """Test that warning is logged when use_host_network=True and max_num_sandboxes > 1."""+ mock_urandom.side_effect = [b'container_id', b'session_key']+ mock_encodebytes.side_effect = ['test_container_id', 'test_session_key']++ mock_container = MagicMock()+ mock_container.name = 'oh-test-test_container_id'+ mock_container.status = 'running'+ mock_container.image.tags = ['test-image:latest']+ mock_container.attrs = {+ 'Created': '2024-01-15T10:30:00.000000000Z',+ 'Config': {+ 'Env': ['OH_SESSION_API_KEYS_0=test_session_key'],+ 'WorkingDir': '/workspace',+ },+ 'HostConfig': {'NetworkMode': 'host'},+ 'NetworkSettings': {'Ports': None},+ }+ mock_docker_client.containers.run.return_value = mock_container++ # Create service with host network AND max_num_sandboxes > 1+ service = DockerSandboxService(+ sandbox_spec_service=mock_sandbox_spec_service,+ container_name_prefix='oh-test-',+ host_port=3000,+ container_url_pattern='http://localhost:{port}',+ mounts=[],+ exposed_ports=[+ ExposedPort(+ name=AGENT_SERVER, description='Agent server', container_port=8000+ ),+ ],+ health_check_path='/health',+ httpx_client=mock_httpx_client,+ max_num_sandboxes=3, # > 1+ docker_client=mock_docker_client,+ use_host_network=True,+ )++ with patch.object(service, 'pause_old_sandboxes', return_value=[]):+ await service.start_sandbox()++ # Verify warning was logged about port collision risk+ mock_logger.warning.assert_called_once()+ warning_message = mock_logger.warning.call_args[0][0]+ assert (+ 'Host network mode is enabled with max_num_sandboxes > 1' in warning_message+ )+ assert 'port collision' in warning_message.lower()++ @patch('openhands.app_server.sandbox.docker_sandbox_service._logger')+ @patch('openhands.app_server.sandbox.docker_sandbox_service.base62.encodebytes')+ @patch('os.urandom')+ async def test_start_sandbox_host_network_no_warning_single_sandbox(+ self,+ mock_urandom,+ mock_encodebytes,+ mock_logger,+ mock_sandbox_spec_service,+ mock_httpx_client,+ mock_docker_client,+ ):+ """Test that no warning is logged when use_host_network=True and max_num_sandboxes=1."""+ mock_urandom.side_effect = [b'container_id', b'session_key']+ mock_encodebytes.side_effect = ['test_container_id', 'test_session_key']++ mock_container = MagicMock()+ mock_container.name = 'oh-test-test_container_id'+ mock_container.status = 'running'+ mock_container.image.tags = ['test-image:latest']+ mock_container.attrs = {+ 'Created': '2024-01-15T10:30:00.000000000Z',+ 'Config': {+ 'Env': ['OH_SESSION_API_KEYS_0=test_session_key'],+ 'WorkingDir': '/workspace',+ },+ 'HostConfig': {'NetworkMode': 'host'},+ 'NetworkSettings': {'Ports': None},+ }+ mock_docker_client.containers.run.return_value = mock_container++ # Create service with host network AND max_num_sandboxes = 1+ service = DockerSandboxService(+ sandbox_spec_service=mock_sandbox_spec_service,+ container_name_prefix='oh-test-',+ host_port=3000,+ container_url_pattern='http://localhost:{port}',+ mounts=[],+ exposed_ports=[+ ExposedPort(+ name=AGENT_SERVER, description='Agent server', container_port=8000+ ),+ ],+ health_check_path='/health',+ httpx_client=mock_httpx_client,+ max_num_sandboxes=1, # = 1, no warning expected+ docker_client=mock_docker_client,+ use_host_network=True,+ )++ with patch.object(service, 'pause_old_sandboxes', return_value=[]):+ await service.start_sandbox()++ # Verify no warning was logged about port collision+ mock_logger.warning.assert_not_called()