【免费下载链接】OpenShellOpenShell is the safe, private runtime for autonomous AI agents.项目地址https://gitcode.com/gh_mirrors/op/OpenShell点击查看免费下载导读本文基于 OpenShell 仓库中 Podman 计算驱动的官方网络说明 crates/openshell-driver-podman/NETWORKING.md完整讲解该驱动如何在不创建 veth、不发布端口、不配置 nftables、不需要CAP_NET_ADMIN的前提下让无特权 AI Agent 沙箱获得受监督的网络出口工作负载容器使用networknone其 DNS 与 TCP 流量经私有 Unix 套接字上的认证 gRPC 通道由独立 supervisor 容器在 Podman 主机网络上代为放行。读完本文你将理解外层网络围栏outer network fence的实现与验证方式、supervisor 主机网络的接入形态、两类容器的网络职责划分以及官方故障排查清单背后的源码依据。1. 网络拓扑总览一条不经过 veth 的数据通路官方文档开篇即给出该驱动的核心网络立场只有外部 supervisor 拥有外部网络连接能力。工作负载容器使用networknone它的回环 DNS 中继与 TCP 套接字中介通过受保护的 Unix 套接字触达 supervisor而不是经由 veth 或代理环境变量。其数据流示意图为workload container supervisor container agent - sandbox -- private UDS / gRPC - policy proxy - host network - destination | -- authenticated gateway session对应到仓库源码这一两容器 一通道的模型在 crates/openshell-driver-podman/src/container.rs 中逐项落实工作负载容器openshell-sandbox的netns.nsmode被硬编码为none同时networks.clear()、portmappings.clear()、hostadd.clear()即不挂任何网络命名空间、不发布端口、不添加主机别名工作负载容器被挂载一个名为openshell-channel-id的私有命名卷channel volume到/.openshell/channel用于承载 bootstrap 与双向 mTLS 材料supervisor 容器openshell-supervisor的netns.nsmode被设置为hostnetworks.clear()、portmappings.clear()以 Podman 主机网络的身份对外出口同时只读挂载同一 channel 卷roz共享 SELinux 重标记。也就是说agent 产生的任何出口流量都无法直接在主机网络上出现——它必须先经过 sandbox 内的回环 DNS 中继与 TCP 中介再经由私有 Unix 套接字上的 gRPC 连接交给 supervisor由 supervisor 依据策略代理出去。这个设计把谁能上网和出去的内容是否被授权收敛到了唯一一个受信任进程上。2. 外层网络围栏默认拒绝出口2.1 创建时不给任何网络能力文档 Outer network fence 一节列出驱动在启动容器时的硬性约束创建工作负载时不带网络、不带主机别名、不发布端口、不附加任何 capabilities启动前与重启前驱动都要检查 Podman inspect 响应确认隔离围栏仍然成立sandbox 在运行 agent 之前自行安装 seccomp 中介与 Landlock 约束驱动不创建网络命名空间、不配置 nftables、不需要CAP_NET_ADMIN。源码中的落实分两层镜像规范层crates/openshell-driver-podman/src/container.rs工作负载的cap_drop [ALL]附加 capabilities 为空同时设置sysctl net.ipv4.ip_unprivileged_port_start 0这样无特权的 sandbox 回环 DNS 中继可以在不持有任何 capability 的情况下把 DNS 服务绑定到 53 端口。运行时验证层crates/openshell-driver-podman/src/client.rsverify_isolation_fence在启动前后通过/libpod/containers/{id}/json读取容器 inspect 结果并检查三个条件——host_config.network_mode none、容器非 privileged、network_settings.networks中不出现除none之外的任何网络名。任一条件不满足即返回错误sandbox requires an unprivileged container with network mode none and no attached networks。2.2 围栏证据参与信任投影驱动不仅在运行时检查网络模式还会把检查到的本机事实编码进隔离边界契约。在 crates/openshell-driver-podman/src/isolation.rs 中PodmanOuterFenceEvidence携带container_id、network_mode: none与unexpected_networks被投影为外层围栏保证OuterFenceGuaranteeDefaultDenyEgress默认拒绝出口工作负载没有可用的网络命名空间任何出口天然被拒绝RevocationVerified吊销已验证即使后续撤销凭据流量也无法逃逸ControllerLossFailsClosed控制器丢失时失败关闭即使 supervisor 退出出口依然被拒NoUnmanagedEgressPath不存在非托管的出口路径未发现任何意外的附加网络。单元测试outer_fence_projection_rejects_each_missing_native_factcrates/openshell-driver-podman/src/isolation.rs专门验证容器 ID 为空、network_mode 为bridge、或存在意外网络时证据投影一律失败——保证围栏必须被证明成立而不是被假设成立。2.3 数据面只走一条认证通道Outer network fence 一节的最后一段说明了流量类型与通道的关系TCP 连接建立、TCP 字节流、DNS 请求/应答、生命周期控制操作全部共享同一条认证 gRPC 通道DNS 由 supervisor 解析并授权通用 UDP 不支持。这与 crates/openshell-driver-podman/README.md 中Seccomp socket mediation carries TCP and DNS through one authenticated gRPC connection的表述一致。对需要 UDP 的场景例如 QUIC、NTP本驱动当前不提供放行路径这是设计取舍而非疏漏。3. Supervisor 网络Podman 主机网络与网关回环文档 Supervisor network 一节说明 supervisor 的接入形态与平台差异supervisor 伴生容器使用Podman 主机网络host networkLinux 上supervisor 直连网关的主回环端点loopbackmacOS 上由 Podman Machine 提供主机回环路由host-loopback route上游公司代理只应用于 supervisor不进入工作负载容器网关的 SSH 隧道使用 supervisor 在私有 Unix 套接字上的中继因此驱动不发布 supervisor 端口。这一平台差异在 crates/openshell-driver-podman/src/driver.rs 中有精确实现PodmanEndpointEnvironment::current()根据目标平台选择网关主机——Linux 使用127.0.0.1macOSPodman Machine使用host.containers.internal。随后select_grpc_endpoint在配置未显式指定grpc_endpoint时按是否启用 TLS 拼出http(s)://gateway_host:gateway_port。这正是supervisor 通过主机网络直连网关主回环端点的源码证据。Supervisor 容器本身的配置同样在 crates/openshell-driver-podman/src/container.rsnetns.nsmode host、cap_drop [ALL]且不新增任何 capability、userns使用主机用户命名空间。值得注意的细节是文档强调 supervisor 与工作负载共享工作负载的用户命名空间——但源码注释显示在 rootless Podman 下加入工作负载用户命名空间与主机网络互不兼容因此 supervisor 实际运行在主机用户命名空间nsmode: host同时依靠 channel 卷的共享 SELinux 重标记z来访问共享卷。文档中的共享用户命名空间保留卷 UID/GID 映射指的是工作负载自身的 userns 设置如keep-id而 supervisor 通过同样的 UID/GID 身份与只读挂载来维持共享卷的可读性PID、mount、网络命名空间三者始终相互独立。与网络配置相关的另一项约定是上游代理只作用于 supervisor配置项https_proxy、proxy_auth_file、proxy_ca_bundle都在 crates/openshell-driver-podman/src/config.rs 中定义且由驱动在 sandbox 创建时把凭据以仅 root 可读的 Podman secret方式投递给 supervisor见 crates/openshell-driver-podman/src/driver.rs 的create_sandbox_proxy_auth_secret与validate_sandbox_proxy_ca_bundle。这些凭据从不出现在容器环境变量中也不进入工作负载容器。4. 两类容器的职责边界一张对照表官方 README 用一张属性表界定了工作负载与 supervisor 的差异结合 NETWORKING.md 可整理为网络视角下的职责清单属性工作负载容器openshell-sandboxSupervisor 容器openshell-supervisor网络模式none仅回环Podman 主机网络host出口路径无外部接口、无发布端口策略放行后由主机网络直出UID/GID固定的非 root 工作负载身份相同映射身份Capabilities全部丢弃、不新增全部丢弃、不新增Seccomp运行时默认 sandbox 自装过滤器运行时默认网关 JWT 与上游凭据永不挂载以 Podman secrets 挂载用户卷与 CDI 设备仅挂载到工作负载永不挂载channel 卷私有命名卷可写rw同一卷只读rochannel 卷中的内容同样有严格分工卷内只有 sandbox bootstrap 与 sandbox 侧 TLS 身份supervisor 私钥与运行时描述符存放在 supervisor 的私有文件系统/.openshell/supervisor/层级中具体路径常量见 crates/openshell-driver-podman/src/isolation.rs。此外Landlock 拒绝 agent 访问顶层/.openshell控制层级防止镜像预置的符号链接把私有控制状态别名到用户挂载中。5. 生命周期与就绪网络围栏在重启时依然被验证文档 Troubleshooting 一节提到运行中的工作负载容器本身并不构成就绪——就绪状态以 supervisor 的健康信号为准。这与 crates/openshell-driver-podman/README.md 中Readiness uses the supervisors private health socket; there is no shell, legacy marker, or TCP-listener shortcut互相印证。源码层面crates/openshell-driver-podman/src/watcher.rsinspect_workload在推导工作负载条件时会检查其openshell.ai/isolation-rolesandbox标签并在 supervisor 事件create/start/stop/die/health_status发生时联动工作负载watcher 对 supervisor 的退出/移除事件会停止缺少伴生容器的运行中工作负载。同时网关在发布 Ready 之前还要求 supervisor 完成认证会话README 原文The gateway also requires the authenticated supervisor session before publishing Ready。生命周期事件中的网络含义Start会从 supervisor 私有文件系统中的副本恢复已消费的 sandbox bootstrap重新验证围栏verify_isolation_fence再启动同一对容器Create先构建两个处于停止状态的容器并预置私有归档工作负载先于 supervisor 启动以便其用户命名空间在 supervisor 加入时已存在Delete先移除伴生容器再移除工作负载、channel、workspace 与驱动自有 secrets用户自有卷保留。6. 故障排查清单官方步骤的源码依据文档 Troubleshooting 一节给出了五条排查建议且每条都能在仓库中找到对应实现整理如下现象排查步骤源码依据沙箱不合格探针失败qualification probe用容器日志定位被拒绝的内核/运行时原语不要添加 capabilities 或禁用运行时 seccomp运行时必须通过无特权强制探针含嵌套 seccomp 通知与 Landlock见 README 的 Runtime posture 一节沙箱无法认证 supervisor检查私有 channel 卷、匹配的用户命名空间映射、共享 SELinux 标签channel 卷以rw,z/ro,z挂载见 container.rsbootstrap 与 TLS 材料路径见 isolation.rssupervisor 无法连接网关检查其配置的网关端点、凭据、主机网络、网关主监听器端点自动选择逻辑见 driver.rsLinux 用127.0.0.1、macOS 用host.containers.internalDNS 或出口被拒检查 supervisor 的策略决策不要给工作负载加网络、不要加解析器绕过、不要加直达网关的路由出口必须经认证 gRPC 通道由 supervisor 代理见外层围栏投影 isolation.rs配对未就绪Pair not Ready检查 supervisor 健康套接字与网关会话仅容器运行不构成就绪watcher 依赖 supervisor 健康事件见 watcher.rs官方文档建议配合 驱动总览 README 与 Podman 运行时文档 使用后者用于查阅具体的运行时选项如 userns 模式、networknone语义。7. 运维观察手段文档与源码给出了两组实用的观测方式1. 用 sandbox-ID 标签区分两类容器。两个容器共享同一个 sandbox-ID 标签但角色标签不同工作负载为openshell.ai/isolation-rolesandboxsupervisor 为openshell.ai/isolation-rolesupervisor常量定义见 crates/openshell-driver-podman/src/isolation.rs。可直接用 Podman 过滤查看podman ps -a --filter labelopenshell.ai/isolation-rolesandbox podman ps -a --filter labelopenshell.ai/isolation-rolesupervisor podman inspect container-id | jq .[0] | {NetworkMode: .HostConfig.NetworkMode, Privileged: .HostConfig.Privileged, Networks: .NetworkSettings.Networks}其中 inspect 的三个字段NetworkMode、Privileged、Networks正是驱动在启动前后验证围栏时检查的对象见 crates/openshell-driver-podman/src/client.rs。2. 通过网关/驱动日志观测。驱动在连接 Podman 时会记录 cgroup 版本、网络后端、rootless 状态等信息crates/openshell-driver-podman/src/driver.rs并且要求 cgroups v2否则启动失败并提示systemd.unified_cgroup_hierarchy1。网络相关的问题通常能在围栏验证失败或supervisor 无法建立认证会话的日志中直接定位。8. 总结网络最小权限模型的三个要点回顾 NETWORKING.md 与源码可以把这套网络模型归纳为三条原则工作负载零网络面networknone 无端口发布 无 capabilities让 agent 容器在操作系统层面就不具备出口能力围栏在启动前、重启前都被 inspect 复核任何偏离都会导致失败关闭。唯一出口归 supervisor所有 TCP/DNS 流量经认证 gRPC 通道交给 supervisor由策略与网关会话授权后在主机网络发出通用 UDP 明确不支持。代理与凭据不出容器环境上游代理配置、网关 JWT、TLS 材料以 Podman secrets 与私有文件系统投递channel 卷只承载 sandbox bootstrap 与 sandbox 侧 TLS 身份保证秘密最小暴露。这种外部无接口、内部全监督的网络形态是 OpenShell 让无特权 AI Agent 在受控边界内运行的核心前提之一。相关实现可继续深入阅读 crates/openshell-driver-podman/src/container.rs、crates/openshell-driver-podman/src/client.rs、crates/openshell-driver-podman/src/isolation.rs 与 crates/openshell-driver-podman/src/watcher.rs。赞分享【免费下载链接】OpenShellOpenShell is the safe, private runtime for autonomous AI agents.项目地址https://gitcode.com/gh_mirrors/op/OpenShell点击查看免费下载相关推荐Podman 网络选项 --interface-name 深度解析为 network create 指定宿主接口及其驱动语义Podman 网络选项 interface name 深度解析为 network create 指定宿主接口及其驱动语义 本文聚焦 Podman 的 inte容器运行时云原生CLIPodman 网络配置检查实战podman network inspect 命令、JSON 输出与 Go 模板格式化全解析Podman 网络配置检查实战podman network inspect 命令、JSON 输出与 Go 模板格式化全解析 导读 podman network容器运行时云原生CLI深入解析 reth network crateP2P 网络的四大任务、核心接口与事件驱动模型深入解析 reth network crateP2P 网络的四大任务、核心接口与事件驱动模型 本篇围绕 reth 仓库中 network 架构文档 https区块链上一篇CANN/amct Qwen3.6-MoE NPU量化实践下一篇mpv EDL编辑决策列表格式全解析语法规范、高级特性与源码级实现原理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考