Sandboxes 隔离执行与凭据/网络边界

安全定位

Sandbox 是隔离的临时执行环境，用来运行 Agent 生成的代码、文件操作和临时服务。隔离降低主基础设施风险，但不是完全信任边界：网络、挂载、凭据代理、公开 Service URL 和快照都可能把能力带入/带出 Sandbox。

Cloud 页面列出的 GCP US/EU/APAC 与 AWS US 均为 GA。Self-hosted 是否可用取决于 Enterprise entitlement、云/区域和 Helm feature，部署前需确认合同与当前支持矩阵。

默认网络不是 deny-all

无 access_control 时：HTTP/HTTPS 80/443 可访问任意 host，其他 raw TCP 默认阻断。配置：

allow_list：真正 default-deny，HTTP/HTTPS 也必须逐个列出；raw TCP 只能以 host:port 显式开放。
deny_list：HTTP/HTTPS 默认放行，只拦列出的 host，不能打开 raw TCP。
allow 与 deny 不能同时使用。

生产运行不可信代码应优先 allowlist，并列出模型、代码仓库、包源和业务 API 的精确域名/端口。通配符需防子域接管、DNS rebinding 与 redirect 绕过。

Auth Proxy

Proxy sidecar 在匹配的出站请求中注入 credential，真实值来自 Workspace Secret 或 write-only opaque config，不进入 Sandbox filesystem/env/history。

静态 rule first-match-wins；若静态 rule 命中，不再调用 callback。
AWS 用 SigV4，当前只支持 access key/secret，不含 session token/assume-role。
GCP 用 service-account JSON proxy auth；真实 JSON 禁止以普通环境变量传入。
Callback 可动态返回 header，缓存 60–3600 秒；transport/non-2xx/非法 JSON 时 fail closed 为 502。
callback endpoint 自身必须校验 HMAC/共享 Secret、限流并防重放。

短期 GitHub App token 等用 opaque rule 比长期 PAT 更合适。任何需要 CLI “看见凭据”的场景只放非敏感 placeholder，由 Proxy 替换。

Mount 与 Snapshot

Mount 支持 S3、GCS 和 public Git，挂载路径必须位于 /mnt/mounts，ID/path 在同一 Sandbox 内唯一。云凭据放 Workspace Secret，不能作为文件或命令参数。

Snapshot 可从公开/私有 Docker image、Dockerfile build 或运行中 Sandbox capture：

私有 Registry credential 是持久资源，按最小范围创建并定期轮换。
Dockerfile context 自动排除 .git，仍要用 .dockerignore 排除 Secret、缓存和大文件。
Snapshot 会固化 filesystem，capture 前清理 token、SSH key、shell history、临时数据。
固定基础镜像 digest、扫描 CVE/SBOM，旧 Snapshot 要有过期与重建策略。

权限模型

默认只有 Creator 能执行命令、读写文件、开 Tunnel、访问 Service URL；同 Workspace 的其他成员需要 sandboxes:exec。生命周期操作仍分别受 create/read/update/delete 权限。跨 Workspace 资源被隐藏为 not found。

sandboxes:exec 等于完整运行时交互权，不是只读分享。需要演示时优先短时 Service share link，而不是赋予执行权。

生命周期

Sandbox 有两段 TTL：

running -- idle_ttl_seconds --> stopped -- delete_after_stop_seconds --> deleted

默认 idle 约 600 秒，停止后删除通常约 14 天；0 可禁用自动停止/删除，会产生长期成本与数据残留。Command 另有执行 timeout、无客户端 idle timeout（默认 5 分钟）和完成后 session TTL。timeout=0 代表不限制执行，并不禁用 disconnect idle kill。

所有生产任务使用 finally/reaper 删除 Sandbox；即使 API 调用失败也要有后台清理。长期进程用明确的 idle/session TTL 和心跳，禁止无限 TTL 作为默认值。

Service URL 与 Tunnel

Service URL 把 Sandbox 内 HTTP 服务通过带 token 的 URL 暴露出来；Share Link 持有者即使没有 LangSmith 账号也能访问，直到 token 过期。不要在 URL/query 中放敏感数据；服务本身仍做 auth、CSRF/CORS 与输入校验。

Tunnel 适合开发者临时 TCP 调试，不应作为生产网络通道。审计创建者、端口、过期时间并在 Sandbox stop/delete 时强制关闭。

生产验收

默认 allowlist egress，验证 redirect、DNS、IPv6 和 raw TCP 都不能绕过。
恶意代码无法读取 Workspace Secret、Proxy opaque value 或宿主 filesystem。
Creator、同 Workspace 无 exec、有 exec、跨 Workspace 四类身份均做负向测试。
Snapshot/Mount/Registry/Service URL 分别设生命周期和审计。
Sandbox/Command TTL、断连、进程 kill、费用与清理指标可观察。
任意公开 URL、安装包源、Git checkout 和模型响应都当作不可信输入。