OpenSandbox /v1/isolated/capabilities 返回 available:false 怎么排查【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandboxGET /v1/isolated/capabilities是 execd 隔离会话isolated session的探测端点。当它返回available: false时说明这个 sandbox 里无法创建 bubblewrap 隔离会话——所有/v1/isolated/*的写操作会返回503SDK 也不会静默回退到非隔离 API需要由调用方自己决定降级或报错。这个排查场景适用于在 OpenSandbox 里通过 curl 或各语言 SDK 使用 isolated session 时遇到available: false的读者前提是你已经能访问 sandbox 内 execd 的 HTTP 端口默认44772。先看完整响应里的 message 字段按 execd OpenAPI 规范/v1/isolated/capabilities的响应体除available外还有一个message字段描述为“diagnostic message when isolation is unavailable”即隔离不可用时的诊断信息。排查的第一步就是把它完整打出来curl -s http://localhost:44772/v1/isolated/capabilities如果 execd 配置了 access token--access-token/EXECD_ACCESS_TOKEN请求需要带上X-EXECD-ACCESS-TOKEN头。available为false时Isolation Sessions 文档给出的原因范围是可信的 native workload gate 缺失或不可信bubblewrapbwrap缺失宿主机无法创建所需 namespace缺CAP_SYS_ADMIN、user-ns sysctl 受限等。message会指向具体是哪一类下面的检查就按这三条线索展开。确认平台与组件版本隔离会话是Linux only非 Linux 的 execd 构建直接返回available: false这不是故障换到 Linux sandbox 镜像即可。版本方面文档要求execd 1.0.20 才有基础隔离会话支持 1.0.21 推荐binds、List sessions、uid_mode: userns和默认可写 allowlist如果用opensandbox-server拉起 sandbox需要 server 0.2.1因为由 server 负责在 execd 镜像声明bootstrap.execd.isolation时注入CAP_SYS_ADMIN、apparmorunconfined以及bwrap所需的 tmpfs 挂载。另外注意setpriv_available/userns_available两个字段是 execd v1.0.21 之后才有的只有main分支较新构建才会返回老版本 execd 会省略这两个字段客户端必须容忍缺失。响应示例文档示例数值以实际输出为准{ available: true, isolator: bwrap, version: 0.9.0, setpriv_available: true, userns_available: false, commit_supported: false, diff_supported: false }排查 native workload gate文档明确说明/capabilities报告available: false的两种情况之一是 “native workload gate cannot be opened as a trusted executable”。这个 gate 是 session 启动时的 fail-closed 检查机制可信路径是/opt/opensandbox/opensandbox-session-gate。使用公开发布的 execd 镜像gate 已随镜像自动安装一般不需要处理。从源码构建 execd必须在启动 execd 之前手动构建并安装 gate见 execd 组件文档cd components/execd make build-session-gate sudo make install-session-gate # /opt/opensandbox/opensandbox-session-gate (mode 0555)sudo make install-session-gate会以 root 权限把编译好的 helper 复制到固定路径/opt/opensandbox/opensandbox-session-gate执行前需要 root/sudo 权限。安装后检查它是否存在、权限是否符合要求ls -l /opt/opensandbox/opensandbox-session-gate文档要求该路径及其父目录保持 root 属主、不可被 group 或 world 写。属主或权限不对时 gate 会被判为“untrusted”同样导致available: false。如果 sandbox 内文件系统被其他进程改写过重新执行安装命令并核对属主。其他 execd API/command、/session、/files等在没有 gate 时仍正常工作只是 isolated session 的能力探测和创建会 fail closed——这也是判断“问题出在隔离子系统而不是 execd 本身”的依据。排查 bwrap 与 namespace 能力第二条线索是bwrap二进制本身缺失或无法启动。bwrap由 execd 静态嵌入、启动时释放到 execd 二进制同目录正常情况下不需要基础镜像预装 bubblewrap 包如果message指向 bwrap优先确认 execd 版本是否满足上面 1.0.20 的要求。第三条线索是 namespace 权限创建 mount/PID namespace 需要CAP_SYS_ADMIN。用opensandbox-server部署时确认 server 版本 0.2.1 且 sandbox 镜像声明了bootstrap.execd.isolation否则权限不会被注入。如果依赖uid_mode: userns宿主还需要kernel.unprivileged_userns_clone1sysctl 被收紧的环境里 userns 模式会不可用。验证修复处理完对应原因后重新探测并创建一次会话确认端到端可用沿用 Isolation Sessions 文档 Quick Start 的命令# 探测 curl -s http://localhost:44772/v1/isolated/capabilities # 创建会话 SESSION$(curl -s -X POST http://localhost:44772/v1/isolated/session \ -H Content-Type: application/json \ -d { profile: strict, workspace: {path: /workspace, mode: overlay}, idle_timeout_seconds: 300 } | jq -r .session_id) # 运行一条命令 curl -N -X POST http://localhost:44772/v1/isolated/session/$SESSION/run \ -H Content-Type: application/json \ -d {code: export X1; echo $X, timeout_seconds: 30} # 清理 curl -X DELETE http://localhost:44772/v1/isolated/session/$SESSION成功条件是 capabilities 返回available: true、创建会话拿到session_id、run 的 SSE 流正常输出。几个容易误判的边界缺overlayfs不会把available翻成false。overlay 探测只影响 Phase 2 的commit/diff支持但在缺少 overlayfs 的宿主上默认 overlay 模式的会话创建仍可能在运行时失败。依赖workspace.mode: overlay时要在宿主上单独确认 overlayfs 支持。available: true不代表所有uid_mode都能用。setpriv_available只反映 execd 默认 UID/GID 的路径请求不同的 UID/GID 时仍可能返回503 NOT_SUPPORTED。commit_supported/diff_supported目前是 Phase 2 占位固定返回 503不要把它当作available: false的故障信号。session 创建参数在创建后不可变run不能覆盖隔离字段。下一步文档中可用的相关入口Isolation Sessions 指南配置、workspace 模式、限制、execd 组件文档构建与 gate 安装、execd OpenAPI 规范端点与错误码定义、隔离配置示例 isolation.example.toml以及设计说明 OSEP-0013。【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考