OpenShell/crates/openshell-driver-podman/NETWORKING.md

Podman Networking

Only the external supervisor has external network connectivity. The workload container uses network=none; its loopback DNS relay and TCP socket mediation reach the supervisor through a protected Unix socket, not a veth or proxy environment variable.

workload container                       supervisor container
agent -> sandbox -- private UDS / gRPC -> policy proxy -> host network -> destination
                                            |
                                            +-- authenticated gateway session

Outer network fence

The driver creates the workload without networks, host aliases, published ports, or added capabilities. It checks the Podman inspect response before launch and restart. The sandbox installs seccomp mediation and Landlock before executing the agent. It does not create network namespaces, configure nftables, or require CAP_NET_ADMIN.

TCP opens, TCP byte streams, DNS requests/replies, and lifecycle operations share the authenticated gRPC channel. DNS is resolved and authorized by the supervisor. General UDP is unsupported.

The driver mounts a read-only, driver-owned /etc/resolv.conf into the workload with nameserver 127.0.0.53. This prevents the disconnected Podman network namespace from replacing the policy-DNS relay with a runtime resolver. The supervisor answers host.openshell.internal with a trusted concrete destination: 127.0.0.1 on native Linux, the configured Podman Machine host address on macOS. That destination is part of the supervisor bootstrap and is reapplied when a sandbox restarts.

Supervisor network

The supervisor companion uses Podman's host network. On Linux it connects to the gateway's primary loopback endpoint. On macOS, Podman Machine provides the host-loopback route. The upstream corporate proxy applies only to the supervisor. The gateway's SSH tunnel uses the supervisor relay over its private Unix socket, so the driver does not publish a supervisor port.

These runtime-managed network helpers are outside the workload trust boundary. Sharing the workload's user namespace preserves volume UID/GID mapping; it does not share the workload's PID, mount, or network namespaces.

Troubleshooting

Inspect both containers with the same sandbox-ID label, distinguishing openshell.ai/isolation-role=sandbox from openshell.ai/isolation-role=supervisor.

• Sandbox fails its qualification probe: use its log to identify the denied kernel/runtime primitive. Do not add capabilities or disable runtime seccomp.
• Sandbox cannot authenticate to supervisor: check the private channel volume, matching user namespace mappings, and shared SELinux label.
• Supervisor cannot connect: inspect its configured gateway endpoint, credentials, host network, and the gateway's primary listener.
• DNS or egress denied: inspect supervisor policy decisions. Do not add a workload network, resolver bypass, or direct gateway route.
• Pair is not Ready: check the supervisor health socket and gateway session. A running workload container alone does not establish readiness.

See the driver overview and Podman runtime documentation for runtime options.