---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags: [langchain, langsmith, sandbox, isolation, security]
topic: LangSmith Sandboxes 隔离执行、凭据、网络与生命周期
sources:
  - "https://docs.langchain.com/langsmith/sandbox-auth-proxy"
  - "https://docs.langchain.com/langsmith/sandbox-cli"
  - "https://docs.langchain.com/langsmith/sandbox-mounts"
  - "https://docs.langchain.com/langsmith/sandbox-permissions"
  - "https://docs.langchain.com/langsmith/sandbox-sdk"
  - "https://docs.langchain.com/langsmith/sandbox-service-urls"
  - "https://docs.langchain.com/langsmith/sandbox-snapshots"
  - "https://docs.langchain.com/langsmith/sandboxes"
last_verified: 2026-08-11
---

# 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：

```text
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 时强制关闭。

## 生产验收

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