# Docker Host Mode vs Bridge Mode in OpenSandbox: Networking Architecture and Implementation

> Explore Docker host mode vs bridge mode in OpenSandbox. Learn how OpenSandbox uses host mode for sandbox sharing and bridge mode for multi-tenant isolation with network policies.

- Repository: [Alibaba/OpenSandbox](https://github.com/alibaba/OpenSandbox)
- Tags: deep-dive
- Published: 2026-03-08

---

**OpenSandbox supports Docker host mode for single-tenant sandbox sharing and bridge mode for multi-tenant isolation with network policy enforcement.**

OpenSandbox provides flexible container networking through two distinct Docker configurations: **host mode** and **bridge mode**. Understanding the differences between Docker host mode vs bridge mode is essential for deploying secure, scalable sandbox environments, as each mode imposes specific constraints on port allocation, network isolation, and security policy enforcement.

## Core Architectural Differences

### Network Stack Isolation

In **host mode**, sandbox containers share the host's network namespace, binding ports directly to the host interface. This eliminates network isolation but simplifies connectivity.

In **bridge mode**, each sandbox operates within an isolated bridge network. Containers receive private IP addresses, and the system exposes only a single proxy port (default `44772`) to the host. This architecture enables multiple sandboxes to coexist on a single machine without port conflicts.

### Port Allocation and Density

**Host mode** restricts deployment to one sandbox per host (or requires pre-allocated dedicated ports), as containers compete for the host's port space. **Bridge mode** allows unlimited sandboxes per host because the internal execd proxy multiplexes traffic through a single host port, routing requests via path-based addressing (`/proxy/{port}`).

### Network Policy and Security Constraints

Bridge mode exclusively supports the `networkPolicy` parameter for egress filtering. When configured with an egress sidecar image, OpenSandbox injects a sidecar container with `NET_ADMIN` capabilities to enforce traffic rules. Host mode explicitly rejects `networkPolicy` requests, returning an `INVALID_PARAMETER` error because the shared namespace prevents granular traffic control.

## Implementation in OpenSandbox

### Configuration Validation

The Docker service reads the `network_mode` setting from the application configuration and validates it against supported values. According to the source code in [`server/src/services/docker.py`](https://github.com/alibaba/OpenSandbox/blob/main/server/src/services/docker.py), the system defaults to host mode but accepts explicit configuration:

```python

# server/src/services/docker.py

self.network_mode = (self.app_config.docker.network_mode or HOST_NETWORK_MODE).lower()
if self.network_mode not in {HOST_NETWORK_MODE, BRIDGE_NETWORK_MODE}:
    raise ValueError(f"Unsupported Docker network_mode '{self.network_mode}'.")

```

### Host Mode Limitations

When operating in host mode, the service actively rejects sandbox requests containing network policies. The validation logic raises an HTTP 400 exception:

```python
if self.network_mode == HOST_NETWORK_MODE:
    raise HTTPException(
        status_code=status.HTTP_400_BAD_REQUEST,
        detail={"code": SandboxErrorCodes.INVALID_PARAMETER,
                "message": "networkPolicy is not supported when docker network_mode=host."},
    )

```

### Bridge Mode Sidecar Injection

Bridge mode enables advanced networking features through sidecar injection. When an egress image is configured, OpenSandbox creates a sidecar container with `NET_ADMIN` capability and binds the proxy port, while the main sandbox container shares the sidecar's network namespace:

```python

# Sidecar host config assertions from server/tests/test_docker_service.py

assert "NET_ADMIN" in sidecar_kwargs["host_config"]["cap_add"]
assert "44772" in sidecar_kwargs["host_config"]["port_bindings"]

# Main container shares netns

assert main_kwargs["host_config"]["network_mode"] == "container:sidecar-id"

```

### Endpoint Resolution Differences

The `get_endpoint` method generates different URL patterns based on the active mode:

- **Host mode**: Returns `{host-ip}:{container-port}` with direct port access
- **Bridge mode**: Returns `{host-ip}:44772/proxy/{container-port}` routing through the execd proxy

## Configuration Examples

### Host-Mode Deployment

Use host mode for single-sandbox deployments where direct port access is required:

```toml
[server]
host = "0.0.0.0"
port = 8080

[runtime]
type = "docker"
execd_image = "opensandbox/execd:v1.0.6"

[docker]
network_mode = "host"

```

### Bridge-Mode Deployment

Use bridge mode for multi-tenant environments requiring network isolation and egress policies:

```toml
[server]
host = "0.0.0.0"
port = 8080

[runtime]
type = "docker"
execd_image = "opensandbox/execd:v1.0.6"

[docker]
network_mode = "bridge"
host_ip = "host.docker.internal"

```

## Code Implementation Details

### Unit Test: Network Policy Rejection

The test suite verifies that host mode correctly blocks network policies:

```python
def test_network_policy_rejected_on_host_mode(mock_docker):
    cfg = _app_config()
    cfg.docker.network_mode = "host"
    service = DockerSandboxService(config=cfg)

    request = CreateSandboxRequest(
        image=ImageSpec(uri="python:3.11"),
        networkPolicy=NetworkPolicy(default_action="deny", egress=[]),
    )

    with pytest.raises(HTTPException) as exc:
        service.create_sandbox(request)

    assert exc.value.status_code == status.HTTP_400_BAD_REQUEST

```

### Unit Test: Bridge Mode Sidecar Verification

Tests confirm that bridge mode properly configures the sidecar architecture:

```python
def test_egress_sidecar_injection_and_capabilities(mock_docker):
    cfg = _app_config()
    cfg.docker.network_mode = "bridge"
    cfg.egress = EgressConfig(image="egress:latest")
    service = DockerSandboxService(config=cfg)
    
    # Assertions confirm sidecar has NET_ADMIN and port bindings

    # Main container shares netns and drops NET_ADMIN

```

## Summary

- **Host mode** shares the host network namespace, supporting only one sandbox per machine and rejecting all `networkPolicy` configurations.
- **Bridge mode** provides isolated networking through a bridge interface, enabling multiple sandboxes per host and supporting egress filtering via sidecar injection.
- **Sidecar containers** in bridge mode require `NET_ADMIN` capabilities and expose port `44772` for the execd proxy to route traffic.
- **Endpoint resolution** differs between modes: host mode uses direct port mapping (`host:port`), while bridge mode uses proxy paths (`host:44772/proxy/port`).
- **Configuration** requires setting `docker.network_mode` in the TOML config file, with optional `docker.host_ip` for containerized server deployments.

## Frequently Asked Questions

### Can I use network policies with Docker host mode in OpenSandbox?

No. OpenSandbox explicitly rejects `networkPolicy` parameters when running in host mode and returns an `INVALID_PARAMETER` error. The shared host namespace makes granular egress filtering impossible, so you must use bridge mode if you require network policies.

### Why does bridge mode require a sidecar container?

Bridge mode uses a sidecar to enforce egress policies without granting excessive privileges to the sandbox container itself. The sidecar runs with `NET_ADMIN` capabilities to manage iptables rules, while the main sandbox container shares the sidecar's network namespace and drops privileged capabilities, following the principle of least privilege.

### How many sandboxes can run on a single host in each mode?

Host mode supports only one sandbox per host (or requires manual port allocation) because containers bind directly to the host's port space. Bridge mode supports unlimited sandboxes per host because all traffic routes through the single execd proxy port (`44772`), with internal multiplexing handling port conflicts.

### What is the purpose of the `host_ip` configuration parameter?

The `host_ip` parameter resolves the correct IP address for endpoint generation when the OpenSandbox server itself runs inside a Docker container. In bridge mode, set this to `host.docker.internal` (or your host's IP) to ensure sandbox endpoints point to the actual host rather than the container's internal network address.