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 callback

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.

Supervisor callback network

The supervisor companion uses Podman's host network. Host-gateway aliases and the upstream corporate proxy apply 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.

Rootful Podman uses the configured bridge and its gateway address. Rootless local callbacks require the existing pasta path; slirp4netns or unknown helpers require an explicitly remote grpc_endpoint. On macOS, Podman Machine provides the runtime and host-loopback forwarding.

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.io/isolation-role=sandbox from openshell.io/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 call back: inspect its configured gateway endpoint, credentials, host network, and gateway callback 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.