background-agents沙箱可信接入控制面sandbox auth token 作用域设计完整指南【免费下载链接】background-agentsAn open-source background agents coding system项目地址: https://gitcode.com/GitHub_Trending/ba/background-agents在 background-agentsOpen-Inspect这个开源后台 AI 编码代理系统中sandbox auth token 是连接沙箱与控制面的信任基石。它的作用域被严格限定在单个会话每个会话沙箱启动时获得一枚专属令牌用它向控制面发起会话级 HTTP 调用——上报事件、拉取 git 短期凭据、回报错误。理解这套作用域设计是读懂 background-agents 安全架构的关键一步。为什么需要沙箱专属令牌background-agents 采用两层架构控制面Cloudflare Workers Durable Objects负责会话编排、数据库与集成数据面是每会话一个的隔离沙箱内含完整的 Node.js、Python、git、浏览器自动化开发环境运行 OpenCode / Claude Agent 等代理。架构总览见 docs/HOW_IT_WORKS.md。沙箱是半可信执行环境——里面跑的正是可能出错、甚至被恶意指令污染的 AI 代理。因此系统绝不会把长效凭据如长期有效的 GitHub token直接塞进沙箱而是遵循一个核心原则凭据最小化沙箱只拿到证明我是这个会话的短凭据真正的敏感操作由控制面按需代做。在 README.md 的 Token Architecture 表格中四类令牌分工清晰其中Sandbox Auth Token的 Scope 一栏写着Single session仅限单个会话。令牌的生命周期从铸造到退役1️⃣ 启动时铸造与注入控制面创建会话时生成令牌随后在拉起沙箱以 Modal 为例时通过环境变量SANDBOX_AUTH_TOKEN注入见 packages/modal-infra/src/sandbox/manager.pyE2B 等其它 Provider 也遵循同样的每沙箱环境注入模式参考 docs/E2B_SANDBOX_PROVIDER.md。2️⃣ 只存哈希不存明文这是作用域设计中最值得学习的细节。控制面数据库里优先保存auth_token_hashSHA-256 哈希验证时先哈希传入的令牌再做恒定时间比较timingSafeEqual防止时序侧信道验证逻辑packages/control-plane/src/session/sandbox-access.ts明文auth_token字段仅作为旧数据行的兼容回退即使数据库泄露攻击者拿到的也是不可逆的哈希。3️⃣ 每次调用的双重校验沙箱访问/sessions/:id/...等会话路由时路由层先校验 Bearer 令牌再向会话 Durable Object 发起一次往返调用内部端点 verify-sandbox-token 完成最终核验处理器实现在 sandbox.handler.ts。核验通过后请求主体Principal被标记为{ kind: sandbox, sessionId, sandboxId }后续所有权限检查都基于这个会话的沙箱这一身份源码见 packages/control-plane/src/routing/route-admission.ts。作用域设计的三个关键点 ✨关键点一令牌绑定单会话 当前代令牌不只绑定会话 ID还绑定沙箱的当前实例。每次沙箱重启会轮换凭据verifySandboxToken会拒绝已停止的沙箱返回 410而错误上报路径还会对比请求处理前后auth_token_hash是否变化——若凭据已被换代直接返回 403 Sandbox credentials changed。这意味着旧一代沙箱即使还活着、令牌还记在内存里也立即失效杜绝了僵尸沙箱冒充新沙箱的攻击面。关键点二以令牌换取短期凭据而非直接下发沙箱做 git clone/push 时并不持有长效 token。git 会触发 credential helper由它携带 sandbox auth token 调用/sessions/:id/scm-credentials控制面才在服务器端铸造短生命周期的 GitHub App installation token 下发。完整流程描述见 packages/control-plane/README.md。信任链在这里形成一个漂亮的闭环用户会话认证→ 控制面铸造 sandbox auth token → 沙箱 沙箱 → 令牌证明身份 → 控制面按需下发短期 git 凭据关键点三与 WebSocket 令牌的职责分离同一会话有两类会话级令牌各司其职令牌用途传输协议Sandbox Auth Token沙箱→控制面的会话 HTTP 调用事件、凭据、媒体产物HTTPS BearerWebSocket Token浏览器/客户端的实时会话流认证WebSocket分离后沙箱令牌泄露不会暴露实时协作通道反之亦然。对自建 Agent 系统的借鉴清单 ✅作用域最小化把设备/环境身份令牌限定到单个业务对象这里是单会话而不是全局有效。存储只留哈希令牌落地即哈希明文只存在于传输与内存中。恒定时间比较所有令牌校验走 timingSafeEqual避免时序攻击。凭据轮换 代际校验重启即轮换并校验凭据是否被换代让旧实例自动失效。按需代理敏感凭据下游环境不直接持有上游密钥通过身份令牌换取短期凭据。结语background-agents 的 sandbox auth token 看似只是一枚 Bearer 字符串背后却是一套完整的作用域设计单会话绑定、哈希存储、代际轮换、短期凭据代理。它回答了一个通用问题——当 AI 代理在你的代码仓库里自由运行时如何让它够得着工作但碰不到钥匙。如果你想深入多仓库会话、快照恢复等更多机制推荐继续阅读 docs/HOW_IT_WORKS.md 与 docs/AUTH.md。【免费下载链接】background-agentsAn open-source background agents coding system项目地址: https://gitcode.com/GitHub_Trending/ba/background-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 background-agents沙箱可信接入控制面：sandbox auth token 作用域设计完整指南
background-agents沙箱可信接入控制面sandbox auth token 作用域设计完整指南【免费下载链接】background-agentsAn open-source background agents coding system项目地址: https://gitcode.com/GitHub_Trending/ba/background-agents在 background-agentsOpen-Inspect这个开源后台 AI 编码代理系统中sandbox auth token 是连接沙箱与控制面的信任基石。它的作用域被严格限定在单个会话每个会话沙箱启动时获得一枚专属令牌用它向控制面发起会话级 HTTP 调用——上报事件、拉取 git 短期凭据、回报错误。理解这套作用域设计是读懂 background-agents 安全架构的关键一步。为什么需要沙箱专属令牌background-agents 采用两层架构控制面Cloudflare Workers Durable Objects负责会话编排、数据库与集成数据面是每会话一个的隔离沙箱内含完整的 Node.js、Python、git、浏览器自动化开发环境运行 OpenCode / Claude Agent 等代理。架构总览见 docs/HOW_IT_WORKS.md。沙箱是半可信执行环境——里面跑的正是可能出错、甚至被恶意指令污染的 AI 代理。因此系统绝不会把长效凭据如长期有效的 GitHub token直接塞进沙箱而是遵循一个核心原则凭据最小化沙箱只拿到证明我是这个会话的短凭据真正的敏感操作由控制面按需代做。在 README.md 的 Token Architecture 表格中四类令牌分工清晰其中Sandbox Auth Token的 Scope 一栏写着Single session仅限单个会话。令牌的生命周期从铸造到退役1️⃣ 启动时铸造与注入控制面创建会话时生成令牌随后在拉起沙箱以 Modal 为例时通过环境变量SANDBOX_AUTH_TOKEN注入见 packages/modal-infra/src/sandbox/manager.pyE2B 等其它 Provider 也遵循同样的每沙箱环境注入模式参考 docs/E2B_SANDBOX_PROVIDER.md。2️⃣ 只存哈希不存明文这是作用域设计中最值得学习的细节。控制面数据库里优先保存auth_token_hashSHA-256 哈希验证时先哈希传入的令牌再做恒定时间比较timingSafeEqual防止时序侧信道验证逻辑packages/control-plane/src/session/sandbox-access.ts明文auth_token字段仅作为旧数据行的兼容回退即使数据库泄露攻击者拿到的也是不可逆的哈希。3️⃣ 每次调用的双重校验沙箱访问/sessions/:id/...等会话路由时路由层先校验 Bearer 令牌再向会话 Durable Object 发起一次往返调用内部端点 verify-sandbox-token 完成最终核验处理器实现在 sandbox.handler.ts。核验通过后请求主体Principal被标记为{ kind: sandbox, sessionId, sandboxId }后续所有权限检查都基于这个会话的沙箱这一身份源码见 packages/control-plane/src/routing/route-admission.ts。作用域设计的三个关键点 ✨关键点一令牌绑定单会话 当前代令牌不只绑定会话 ID还绑定沙箱的当前实例。每次沙箱重启会轮换凭据verifySandboxToken会拒绝已停止的沙箱返回 410而错误上报路径还会对比请求处理前后auth_token_hash是否变化——若凭据已被换代直接返回 403 Sandbox credentials changed。这意味着旧一代沙箱即使还活着、令牌还记在内存里也立即失效杜绝了僵尸沙箱冒充新沙箱的攻击面。关键点二以令牌换取短期凭据而非直接下发沙箱做 git clone/push 时并不持有长效 token。git 会触发 credential helper由它携带 sandbox auth token 调用/sessions/:id/scm-credentials控制面才在服务器端铸造短生命周期的 GitHub App installation token 下发。完整流程描述见 packages/control-plane/README.md。信任链在这里形成一个漂亮的闭环用户会话认证→ 控制面铸造 sandbox auth token → 沙箱 沙箱 → 令牌证明身份 → 控制面按需下发短期 git 凭据关键点三与 WebSocket 令牌的职责分离同一会话有两类会话级令牌各司其职令牌用途传输协议Sandbox Auth Token沙箱→控制面的会话 HTTP 调用事件、凭据、媒体产物HTTPS BearerWebSocket Token浏览器/客户端的实时会话流认证WebSocket分离后沙箱令牌泄露不会暴露实时协作通道反之亦然。对自建 Agent 系统的借鉴清单 ✅作用域最小化把设备/环境身份令牌限定到单个业务对象这里是单会话而不是全局有效。存储只留哈希令牌落地即哈希明文只存在于传输与内存中。恒定时间比较所有令牌校验走 timingSafeEqual避免时序攻击。凭据轮换 代际校验重启即轮换并校验凭据是否被换代让旧实例自动失效。按需代理敏感凭据下游环境不直接持有上游密钥通过身份令牌换取短期凭据。结语background-agents 的 sandbox auth token 看似只是一枚 Bearer 字符串背后却是一套完整的作用域设计单会话绑定、哈希存储、代际轮换、短期凭据代理。它回答了一个通用问题——当 AI 代理在你的代码仓库里自由运行时如何让它够得着工作但碰不到钥匙。如果你想深入多仓库会话、快照恢复等更多机制推荐继续阅读 docs/HOW_IT_WORKS.md 与 docs/AUTH.md。【免费下载链接】background-agentsAn open-source background agents coding system项目地址: https://gitcode.com/GitHub_Trending/ba/background-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考