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

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, the system defaults to host mode but accepts explicit configuration:

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

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:

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

[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:

[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:

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:

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}