【免费下载链接】OpenShellOpenShell is the safe, private runtime for autonomous AI agents.项目地址https://gitcode.com/gh_mirrors/op/OpenShell点击查看免费下载OpenShell 的 Docker 计算驱动为本地与远程 OpenShell Gateway 提供基于 Docker 的沙箱资源管理它通过bollard客户端操作配置的 Docker API socket以工作负载容器 监督者伴侣容器的双容器模型落地沙箱的强制隔离边界。本文以crates/openshell-driver-docker/README.md为骨架结合 driver 源码、入口二进制、边界供给实现 与 Gateway 配置参考完整讲解该驱动的运行时模型、身份与工作区解析、容器契约、生命周期操作、driver-config 挂载、运行时镜像、Gateway 会话与 TLS以及从DockerComputeConfig到 OTLP 可观测性的全部实现细节与配置示例帮助你理解并实际配置基于 Docker 的 OpenShell 沙箱。驱动概览本地与远程 Gateway 的 Docker 后端openshell-driver-docker是 OpenShell 内置的 Docker 计算驱动核心职责是只负责容器放置、受保护 socket 与不可变的 OCI 资源声明而生命周期、进程、网络、身份与线上行为均由openshell-isolation-interface与openshell-sandbox承担。这一点在 isolation.rs 的模块文档 中被明确表述Docker 本身不参与策略判定只提供隔离的外层栅栏。驱动通过bollardDocker Engine API 的 Rust 客户端见 Cargo.toml 中的bollard 0.20管理沙箱资源socket 自动探测当socket_path未设置时驱动会探测第一个能响应 API ping 的标准本地 socket。源码中的detect_socket()lib.rs 第 805-827 行依次检查DOCKER_HOST环境变量中的unix://路径、/var/run/docker.sock、$HOME/.docker/run/docker.sock与$XDG_RUNTIME_DIR/docker.sock且要求响应头包含Api-Version:而不包含Libpod-Api-Version:用于排除 Podman socket。显式回退显式选择了 Docker 驱动但无候选 socket 响应时回退到/var/run/docker.sock见 lib.rs 第 844-848 行 的socket_path.or_else(detect_socket).unwrap_or(...)。可观测性集成当 Gateway 配置了[openshell.gateway.otlp]时进程内驱动将 span 导出到与 Gateway 相同的 OTLP/gRPC collector独立运行的驱动则接受OPENSHELL_OTLP_ENDPOINT环境变量、从 Gateway RPC metadata 延续 W3C trace context并在优雅关闭时刷新 span。从入口 main.rs 可以看到驱动既可作为独立二进制运行通过--bind-socket、--config、--gateway-bind、--otlp-endpoint等 clap 参数支持OPENSHELL_COMPUTE_DRIVER_SOCKET、OPENSHELL_DOCKER_DRIVER_CONFIG、OPENSHELL_OTLP_ENDPOINT等环境变量也可由 Gateway 进程内加载ComputeDriverService::new_in_process见 lib.rs 第 796-802 行。运行时模型双容器 受控网络每个沙箱由驱动创建两个容器职责严格分离容器角色职责openshell-sandbox工作负载容器内的 PID 1拥有工作负载进程树、seccomp 通知代理、强制性的 Landlock 基线、二进制身份、exec/signal/wait/PTY 操作与 loopback 转发openshell-supervisor独立伴侣容器拥有 Gateway 会话、策略引擎、凭证、拦截 CA、SSH 中继、L7 检查、DNS 策略与外部上游连接两个容器都以非 root身份运行、不请求任何 Linux capabilities并设置no-new-privileges。共享的具名卷承载经过认证的 Unix socket 与沙箱 bootstrap 材料第二个仅监督者可见的卷承载 supervisor JWT 与 Gateway 客户端凭证绝不挂载进工作负载容器。网络的强制隔离模型是本文档最核心的安全设计工作负载容器使用network_modenone。其 seccomp user-notification 代理会中介每一次受支持的 TCP 与 DNS 操作将其归属到发起调用的二进制并通过私有通道把请求发送给监督者监督者先授权、后打开上游连接。Docker 缺失的工作负载网络是当调解失败或被绕过时的强制外层栅栏。这一点在 isolation.rs 第 31-59 行 的DockerOuterFenceEvidence中体现只有当network_mode none且unexpected_networks为空时才建立DefaultDenyEgress、RevocationVerified、ControllerLossFailsClosed、NoUnmanagedEgressPath四项外层栅栏保证任一事实缺失如出现bridge网络都会导致证据投影失败沙箱 fail closed。对应测试见 isolation.rs 第 146-168 行。受信任的监督者伴侣容器使用 Dockerhost 网络可以到达 Gateway 的主 loopback 监听器并主动发起已批准的外部连接。驱动从配置的 supervisor 镜像中通过Docker archive API拷贝受信任的运行时字节extract_first_tar_entry/validate_linux_elf_binary见 lib.rs 第 904-929 行。任何工作负载的启动都不依赖宿主 bind mount 或工作负载镜像提供的工具因此同一套流程在本地、远程与 VM 后端的 Docker daemon 上均可工作。资源准入Resource Admission调用方 driver config 默认被禁用allow_driver_config false见 lib.rs 第 258-283 行的 Default 实现。已有卷需要管理员控制的审批标签原始 bind mount 没有受支持的标签解析器因此在强制策略下会被拒绝。GPU 设备当前被暂时豁免。驱动会在启动前、重启时与对账reconciliation期间反复检查标签。准入策略的完整说明见 resource admission configuration。从源码看资源准入在 lib.rs 第 1185-1291 行 的admit_container_resources中执行对比容器标签中记录的openshell.ai/...资源身份与当前实际挂载清单检查沙箱私有卷的所有权driver、options、标签是否被篡改并要求外部卷的身份记录与实际附着清单完全一致否则返回failed_precondition。身份与工作区Identity and Workspace在创建工作负载之前驱动会执行以下步骤对应 lib.rs 第 490-693 行 的镜像元数据与账户解析逻辑钉住镜像 IDpinning image ID并通过一个已停止的元数据容器读取其 passwd/group 数据库parse_docker_passwd/parse_docker_group解析/etc/passwd、/etc/group并校验格式。解析被策略承认的身份policy identity或回退到镜像Config.User归结为一个精确的非 root UID、主 GID 与补充组集合resolve_docker_identity_from_accounts支持数字或具名的 user/group并依据组成员关系推导 supplementary GIDs。Docker 以该身份启动openshell-sandbox沙箱对每个 canonical 进程与 exec 进程使用完全相同的身份。UID/GID 为 0root或无法解析的符号身份会被拒绝。若镜像未声明USER且策略也未请求则合成 OpenShell 默认的非 root 数字身份DEFAULT_SANDBOX_UID/DEFAULT_SANDBOX_GID与 Podman/Kubernetes/VM 驱动的行为一致。工作区规则绝对的 OCI 工作目录Config.WorkingDir成为工作区空、/或显式的/sandbox声明统一使用/sandbox任何其他 workdir 必须已存在且不含符号链接组件解析出的身份必须能够遍历每一个父目录、并能写入与进入工作目录OpenShell不会修改工作区的属主或权限模式镜像VOLUME声明与用户挂载不得覆盖工作目录、其任一父目录或保留的/.openshell运行时/通道树OpenShell 请求内核在最终身份下验证访问权限因此POSIX ACL 与宿主 LSM 的判定保持权威。容器契约Container ContractREADME 以表格形式定义了驱动为每个容器应用的核心设置这是理解其安全模型的关键设置用途精确的非 rootuser与group_add让沙箱与工作负载拥有不可变的 UID/GID/组身份这是无 capabilities 观测的前提cap_drop ALL、无cap_add、no-new-privileges防止任一容器获得 Linux capabilitiesDocker 默认 seccomp 与 AppArmor 配置保留运行时加固若嵌套 seccomp 通知不可用启动确认 fail closed工作负载network_mode none移除直接的外部路由监督者network_mode host让受信任的监督者到达 Gateway 主 loopback 监听器并主动发起已批准的上游连接restart_policy no保持 canonical 主进程退出的终态性PidsLimit应用配置的沙箱 PID 预算省略sandbox_pids_limit使用 OpenShell 默认值2048见 gateway-config.mdx 注释显式 0 非法私有具名卷一个承载认证的沙箱/监督者通道另一个仅挂载到监督者内含其 JWT 与私有 Gateway 凭证内存内/run/openshell-supervisor-catmpfs只存放公开的监督者 CA 证书与信任包不会让整个/run可写CDI GPU 请求精确分配驱动配置请求的或按数量选择的、通过校验的 CDI 设备从源码看监督者容器使用固定的非 rootSUPERVISOR_UID/SUPERVISOR_GID65534见 lib.rs 第 101-102 行健康检查通过/run/openshell/health.sock进行健康间隔/超时/启动期分别约 250ms / 2s / 60slib.rs 第 94-96 行。另外lib.rs 第 1069-1091 行 的validate_sandbox_template_base显示Docker 沙箱要求模板必须提供镜像且不支持template.agent_socket_path与template.platform_config沙箱还必须携带 launch-scoped 的 Gateway 认证validate_sandbox_authlib.rs 第 1093-1104 行。停止、启动与删除Stop, Start, Delete生命周期操作保持了沙箱的可停留状态语义Stop终止监督者伴侣容器并停止工作负载容器但不删除它。Docker 保留工作负载的可写层与附着的卷。Startstaging 一份全新的沙箱 bootstrap 包重启工作负载容器并创建一个新的监督者伴侣容器。持久性一个被持久停止的沙箱在 Gateway 重启后仍然保持停止状态。Delete强制删除两个容器、驱动拥有的运行时卷以及宿主机私有的运行时描述符。缺失或变更的描述符与通道资源fail closed驱动不会回退运行旧的 combined-supervisor 布局。源码中DockerLifecycleEventFenceslib.rs 第 355-476 行专门处理生命周期竞态Docker 轮询循环可能在 restart 之前观察到已停止的容器并发布过期快照驱动通过对比容器过渡时间戳previous_finished_at、starts_in_progress、stops_requested防止旧观测将新的生命周期操作回归为Error状态。驱动配置挂载Driver Config MountsGateway 将--driver-config-json中的docker块转发给驱动。支持的挂载类型对应 lib.rs 第 731-767 行 的DockerDriverMountConfig枚举serde(tag type)反序列化类型说明附加约束bind绝对 daemon-host 路径仅当[openshell.drivers.docker].enable_bind_mounts true且标签准入显式禁用时才允许volume已存在的具名卷驱动从不创建或删除用户提供的卷bind 支撑的本地卷同样需要enable_bind_mounts truetmpfs内存文件系统可选 size 与 modeimage镜像内路径只读默认开启源码中额外支持的挂载种类安全约束宿主 bind 挂载默认禁用因为它们会把 daemon-host 路径暴露给沙箱请求用户 bind 与 volume 挂载默认只读挂载目标必须是绝对的、规范化的路径且不得与工作区根目录或 OpenShell 控制路径重叠。README 给出的可运行示例使用已有的名为openshell-work的卷挂载到/sandbox/workdocker volume create openshell-work openshell sandbox create \ --driver-config-json {docker:{mounts:[{type:volume,source:openshell-work,target:/sandbox/work}]}} \ -- claude源码中validate_docker_driver_mounts与validate_user_volume_mounts_availablelib.rs 第 1131-1170 行会在创建前检查bind/image 类挂载在启用资源准入时会被reject_unlabelable拒绝volume 必须真实存在inspect_volume必须通过工作区标签准入admit(workspace, volume.labels)且 bind-backed volume 在enable_bind_mounts为 false 时被拒。运行时镜像Runtime Image配置项内容链接方式sandbox_runtime_image内含静态链接 musl的/openshell-sandbox二进制驱动以字节形式提取该二进制并 staging 到已停止的工作负载容器对应常量SANDBOX_BINARY_PATH /.openshell/runtime/openshell-sandboxsupervisor_image内含动态链接 glibc的/openshell-supervisor二进制运行在 host 网络的监督者容器中对应常量SUPERVISOR_IMAGE_CONTROL_BINARY_PATH /openshell-supervisorRelease 与 Gateway 镜像构建会把匹配的镜像标签烘焙进二进制。当未显式配置时两个镜像默认取 OpenShell 的默认值default_sandbox_runtime_image/default_supervisor_image见 lib.rs 第 899-919 行ensure_runtime_image会按image_pull_policy拉取镜像并通过extract_sandbox_binary_bytes从 archive API 提取二进制字节。Gateway 会话与 TLSOPENSHELL_ENDPOINT与 Gateway 认证材料只注入监督者伴侣容器。工作负载永远拿不到沙箱 JWT、Gateway 客户端 TLS 私钥、策略权威或拦截 CA 私钥。未配置 endpoint 时监督者连接127.0.0.1:gateway-port当 Gateway 不在 Docker daemon 主机上时必须设置grpc_endpoint配置了 HTTPS 服务器证书时证书必须把 endpoint 主机包含在 subject alternative namesSAN中。宿主机服务发现驱动把宿主 loopback 发布为host.openshell.internal的后端地址对应源码常量HOST_OPEN_SHELL_INTERNALlib.rs 第 128 行。策略 DNS 通过中介路径解析这个保留名因此策略无需 Docker bridge、容器 DNS 别名或额外的 Gateway listener 即可访问宿主服务。网络前置条件Linux 上的 Docker Engine 直接支持 host 网络Docker Desktop 需要先在 Settings 中启用 host networking且启用 Enhanced Container Isolation 时不支持。监督者独占以下安全关键变量对应 lib.rs 第 98-129 行 的挂载路径常量OPENSHELL_ENDPOINTOPENSHELL_SANDBOX_IDOPENSHELL_SANDBOXOPENSHELL_SANDBOX_TOKEN_FILEOPENSHELL_SSH_SOCKET_PATHOPENSHELL_MAIN_PROCESS_SPEC启用 HTTPS 时的 TLS 路径变量模板与沙箱环境变量被编码进受保护的 bootstrap 中只暴露给工作负载子进程工作负载输入无法覆盖安全关键的监督者变量。完整配置参考以下 TOML 摘自 gateway-config.mdx 的 Docker 小节展示了在 Gateway 中启用 Docker 驱动的完整配置[openshell] version 2 [openshell.gateway] bind_address 127.0.0.1:17670 log_level info compute_driver docker # Gateway-owned bundle injected into the selected local driver. guest_tls_ca /etc/openshell/certs/ca.pem guest_tls_cert /etc/openshell/certs/client.pem guest_tls_key /etc/openshell/certs/client-key.pem [openshell.drivers.docker] socket_path /var/run/docker.sock default_image nvcr.io/nvidia/base/ubuntu:24.04 # Canonical values: always | if_not_present | never. newer is Podman-only. image_pull_policy if_not_present # Value assigned to the openshell.sandbox_namespace label on sandbox containers. sandbox_label docker-dev # Optional override. When omitted, the host-networked supervisor uses the # gateways primary loopback endpoint. grpc_endpoint https://127.0.0.1:17670 # Workload-side runtime. Defaults to the gateway version. # sandbox_runtime_image ghcr.io/nvidia/openshell/sandbox:version # Supervisor runtime. Defaults to the gateway version. # supervisor_image ghcr.io/nvidia/openshell/supervisor:version # Unsafe operator override. Host bind mounts, including Docker local-driver # bind-backed volumes, expose gateway-host paths inside sandboxes and can # negate OpenShell isolation and filesystem controls. enable_bind_mounts false # Omit to use OpenShells 2048-process default. Explicit 0 is invalid. sandbox_pids_limit 2048 # Explicit supervisor-compatible default. RuntimeDefault requires Docker to # report AppArmor support; Localhost/name requires an operator-loaded profile. app_armor_profile Unconfined # Corporate TLS egress proxy. These are supervisor argv settings, not workload # environment variables. Do not embed credentials in the URL. https_proxy https://proxy.corp.example:8443 no_proxy .svc.cluster.local,10.0.0.0/8 # Optional root-owned host file containing user:pass. An http:// proxy also # requires proxy_auth_allow_insecure true as an explicit acknowledgement. proxy_auth_file /etc/openshell/secrets/proxy-auth # Project a host Unix Workload API socket into the supervisor for provider # token exchange. The socket parent must be a dedicated absolute directory. provider_spiffe_workload_api_socket /run/spire/agent.sock注意事项Docker 配置使用sandbox_label旧的sandbox_namespace键会被拒绝。这些字段与 lib.rs 第 154-227 行 的DockerComputeConfig结构一一对应包含allow_driver_config、resource_admission、socket_path、default_image、image_pull_policy、sandbox_label、grpc_endpoint、sandbox_runtime_image、supervisor_bin、supervisor_image、guest_tls_*、ssh_socket_path、sandbox_pids_limitNonZeroI64显式 0 在validate_sandbox_pids_limit中会被拒绝、enable_bind_mounts、upstream_proxyflatten、provider_spiffe_workload_api_socket与app_armor_profile。启动校验validate_configurationlib.rs 第 229-256 行还会额外要求socket_path必须是合法 UTF-8、upstream_proxy配置合法、SPIFFE socket 的父目录必须是专用绝对目录且Gateway 绑定端口不能为 0驱动需要一个固定的非零端口来推导 supervisor endpoint。可观测性OTLP 与 trace 上下文驱动与 Gateway 共享同一套 OTLP 可观测性管线进程内模式Gateway 配置[openshell.gateway.otlp]后驱动 span 通过专用 in-process provider 导出到同一个 collector独立模式通过OPENSHELL_OTLP_ENDPOINT指定 endpoint从 Gateway RPC metadata 延续 W3C trace context并在优雅关闭shutdown_signal处理 SIGTERM/ctrl-cmain.rs 第 86-99 行时刷新 span服务名保持为openshell-driver-docker这样的独立身份otel_tracing.rs 中的compute_driver_tracing!()宏定义并有测试driver_spans_reach_otlp_collector_with_resource_identity验证 span 带资源身份到达 collectorRPC span 使用完全限定的 protobuf 操作名如openshell.compute.v1.ComputeDriver/CreateSandbox服务名与 span kind 区分两侧provisioning_spanlib.rs 第 131-151 行会继承 Gateway 的远程 span context并为docker.provisionspan 记录sandbox.id、sandbox.name、image.ref属性。详细的 OTLP 配置与 driver span 说明见 gateway-config.mdx 的 tracing 小节。小结openshell-driver-docker的安全本质可以概括为三点双重职责分离sandbox 与 supervisor 两个容器、两套私有卷、两种网络模式、强制外层栅栏network_modenone seccomp 通知代理 监督者先授权后联网任何证据缺失都 fail closed、最小化信任面无 capabilities、no-new-privileges、非 root 身份、工作负载永不接触凭证。配置侧则围绕DockerComputeConfig的十几个字段展开其中enable_bind_mounts、sandbox_pids_limit、sandbox_label、grpc_endpoint与guest_tls_*是最常被运维调整的项。结合 lib.rs、isolation.rs 与 gateway-config.mdx 继续深入可以进一步跟踪CreateSandbox到admit_container_resources、resolve_docker_identity_from_accounts、DockerBoundarySpec::provision的完整创建链路以及各边界协议测试对资源声明一致性的约束。赞分享【免费下载链接】OpenShellOpenShell is the safe, private runtime for autonomous AI agents.项目地址https://gitcode.com/gh_mirrors/op/OpenShell点击查看免费下载相关推荐突破60帧限制WaveTools鸣潮工具箱的智能游戏优化革命突破60帧限制WaveTools鸣潮工具箱的智能游戏优化革命 当你为《鸣潮》的帧率限制感到困扰时当你发现高性能硬件在游戏中无法完全发挥潜力时WaveToopi coding-agent 容器化实战Gondolin、Docker 与 OpenShell 三种隔离模式pi coding agent 容器化实战Gondolin、Docker 与 OpenShell 三种隔离模式 pi earendil works/pi数据分析数据工程机器学习Playnite指南把20游戏平台收进一个游戏库Playnite指南把20游戏平台收进一个游戏库 Playnite是一款免费开源的游戏库管理工具能把Steam、Epic、GOG等20多个平台的游戏导入统桌面应用游戏开发上一篇Mermaid Live Editor3分钟学会用代码绘制专业图表的终极指南下一篇深度实战AMD Ryzen处理器硬件级调试工具完全指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考