MiniDock Build 27: Choose Network Isolation per Workload

Host, None, and the Driver Seam

Design claim: Network mode is a workload choice behind a common driver seam, not one universal isolation setting.

Uniformity can hide the wrong contract

Some workloads need ordinary bridge isolation, some need no network, and a few need direct host-stack performance or compatibility. Connectivity is a set of scoped attachments, routes, and names, not an intrinsic property of a container record.

The tempting shortcut is straightforward: force every container through the same bridge path. The shortcut works only while addresses are static and every participant shares one host or trust zone. A universal path either grants unnecessary connectivity, imposes avoidable translation, or cannot satisfy workloads that must share the host stack. Endpoint churn, isolation, or a second host exposes the missing scope and ownership information.

Select behavior behind one seam

The engine selects a network driver or mode whose implementation honors the common endpoint contract with bridge, host, none, or plugin-specific behavior. The mechanism separates membership from packet movement so drivers can implement the same connection contract at different boundaries.

Read the topology by following an endpoint from its sandbox through the selected network boundary, keeping control information separate from packet flow.

  flowchart TB
    subgraph B["bridge (default)"]
      B1["own sandbox
private IP + NAT + DNS
publish ports to expose"]
    end
    subgraph H["host"]
      H1["NO sandbox —
host's real stack
no NAT · no publish · no isolation"]
    end
    subgraph N["none"]
      N1["own sandbox,
loopback only
airgapped by construction"]
    end
    APP["same container image"] --> B
    APP --> H
    APP --> N
    style H1 fill:#fff8ec,stroke:#f2ddb0
      

It compares bridge, host, none, and plugin implementations behind a driver boundary. Its central claim is that each mode states its isolation and connectivity contract explicitly behind the same selection seam; the labels therefore describe authority rather than decorative grouping.

Bridge, host, and none make different promises

host mode doesn't create a NET namespace at all: the container shares the host's real interfaces, so there's no NAT hop (maximum network performance), no port publishing (the app's port is a host port), and no isolation — port clashes and raw-socket access included. Right for network tools and rare latency-critical services. none creates the namespace but leaves only loopback: airgapped by construction, for batch jobs and security-sensitive processing whose only I/O is mounted storage. bridge is the balanced default. The engine's remaining job is honesty at the seam: refuse option combinations a driver can't honor (publishing a port in host mode is meaningless; so is any network I/O in none).

Bridge creates an isolated sandbox attachment, host joins the host namespace without endpoint translation, and none leaves only loopback inside an isolated stack. Trace both the forward and cleanup paths; connectivity is correct only when allocation and removal agree about ownership.

The second figure tests the same model in motion: it shows mode selection producing distinct namespace and attachment behavior.

  sequenceDiagram
    participant U as User
    participant E as Engine
    participant DR as chosen driver
    U->>E: run --network host -p 8080:80 app
    E->>E: validate options against driver capabilities
    E-->>U: error: host driver cannot publish ports
(the app's port is already a host port)
    U->>E: run --network host app
    E->>DR: setup(sandbox: none needed)
    DR-->>E: container joins host stack directly
      

It shows mode selection producing distinct namespace and attachment behavior. The ordering is valid only when it continues to preserve the stated invariant under retries and interruption.

Unsupported combinations should fail clearly

A workload requests port publishing in host mode, so the engine must reject or clearly neutralize an operation that has no separate private endpoint. A stale or conflicting attachment must be refused or withdrawn locally rather than corrupting unrelated network state.

Each mode states its isolation and connectivity contract explicitly behind the same selection seam. The rule binds reachability to explicit, current membership within the correct scope.

Let MiniDock choose isolation deliberately

MiniDock chooses network isolation per workload without scattering mode-specific logic across the daemon. MiniDock now needs that connectivity property without being told which component to edit.