沙箱 CLI - Docs by LangChain

沙盒功能目前处于私密预览阶段。随着我们的迭代，API 和功能可能会发生变化。注册等待列表以获取访问权限。

LangSmith CLI 包含实验性的沙箱命令，用于创建快照、启动沙箱、运行命令、打开交互式 shell 以及建立 TCP 连接隧道到沙箱。沙箱 CLI 命令需要 LangSmith CLI v0.2.26 或更高版本。

安装与认证

安装或升级 LangSmith CLI：

curl -fsSL https://cli.langsmith.com/install.sh | sh
langsmith self-update

使用你的 LangSmith API 密钥对 CLI 进行认证：

export LANGSMITH_API_KEY="<LANGSMITH_API_KEY>"

如果你使用自托管或混合 LangSmith 部署，还需设置端点：

export LANGSMITH_ENDPOINT="https://your-langsmith-instance.com"

CLI 输出默认为 JSON 格式。为列表命令添加 --format pretty 以生成人类可读的表格：

langsmith --format pretty sandbox list

端到端工作流程

每个沙箱都从一个快照启动。从 Docker 镜像构建快照，从该快照创建沙箱，然后在其中运行命令：

langsmith sandbox snapshot build python-slim \
  --docker-image python:3.12-slim \
  --capacity 4gb \
  --wait

langsmith sandbox create my-vm \
  --snapshot-id <SNAPSHOT_ID> \
  --vcpus 2 \
  --memory 1gb \
  --wait

langsmith sandbox exec my-vm -- python --version

使用完沙箱后，将其删除：

langsmith sandbox delete my-vm

管理快照

从 Docker 镜像构建快照：

langsmith sandbox snapshot build my-snapshot \
  --docker-image ubuntu:24.04 \
  --capacity 8gb \
  --wait

对于私有注册表，通过环境变量传递注册表凭据：

langsmith sandbox snapshot build internal-python \
  --docker-image registry.example.com/internal/python:3.12 \
  --registry-url https://registry.example.com \
  --registry-username "$REGISTRY_USERNAME" \
  --registry-password "$REGISTRY_PASSWORD" \
  --wait

从运行中的沙箱捕获文件系统：

langsmith sandbox snapshot capture ml-ready \
  --box my-vm \
  --wait

列出、检查、等待和删除快照：

langsmith sandbox snapshot list
langsmith sandbox snapshot get <SNAPSHOT_ID>
langsmith sandbox snapshot wait <SNAPSHOT_ID>
langsmith sandbox snapshot delete <SNAPSHOT_ID>

管理沙箱

从快照创建沙箱：

langsmith sandbox create my-vm \
  --snapshot-id <SNAPSHOT_ID> \
  --vcpus 4 \
  --memory 1gb \
  --rootfs-capacity 8gb \
  --wait

列出和检查沙箱：

langsmith sandbox list
langsmith sandbox get my-vm
langsmith sandbox wait my-vm

停止和启动沙箱，同时保留其文件系统：

langsmith sandbox stop my-vm
langsmith sandbox start my-vm --wait

更新资源或代理配置：

langsmith sandbox update my-vm --vcpus 8 --memory 2gb
langsmith sandbox update my-vm --proxy-config @proxy.json

资源更改在沙箱下次启动时生效。代理配置更改立即生效。

代理配置

在 create 或 update 命令上使用 --proxy-config @proxy.json 来配置沙箱认证代理。建议使用工作区密钥进行凭据注入，而不是将原始密钥放在本地文件中。

{
  "rules": [
    {
      "name": "openai",
      "match_hosts": ["api.openai.com"],
      "match_paths": [],
      "headers": [
        {
          "name": "Authorization",
          "type": "workspace_secret",
          "value": "Bearer {OPENAI_API_KEY}"
        }
      ],
      "enabled": true
    }
  ],
  "access_control": {
    "allow_list": ["api.openai.com"],
    "deny_list": []
  }
}

有关代理规则的更多信息，请参阅沙箱认证代理。

运行命令

使用 sandbox exec 执行一次性命令：

langsmith sandbox exec my-vm -- uname -a
langsmith sandbox exec my-vm -- ls -la /
langsmith sandbox exec my-vm -- cat /etc/os-release

-- 之后的所有内容都会作为命令发送到沙箱。CLI 将标准输出打印到标准输出，标准错误打印到标准错误，并以沙箱命令的退出码退出。

打开交互式控制台

使用 sandbox console 获取基于 PTY 的交互式 shell：

langsmith sandbox console my-vm
langsmith sandbox console my-vm --shell /bin/sh

你可以将本地 SSH 代理转发到控制台会话：

langsmith sandbox console my-vm --forward-ssh-agent

--forward-ssh-agent 需要本地设置 SSH_AUTH_SOCK。Windows 不支持交互式控制台会话；请改用 SSH 访问。

隧道 TCP 端口

当你需要一个本地 TCP 端口转发到沙箱内监听的服务时，使用 sandbox tunnel。这对于数据库、语言服务器、自定义协议或期望 localhost 的本地工具非常有用。在沙箱中启动一个服务，然后建立隧道连接：

langsmith sandbox exec my-vm -- sh -c 'cd /tmp && nohup python -m http.server 8000 > /tmp/http.log 2>&1 &'
langsmith sandbox tunnel my-vm --remote-port 8000 --local-port 18000

然后在本地连接：

curl http://127.0.0.1:18000

如果省略 --local-port，CLI 将使用与 --remote-port 相同的值：

langsmith sandbox tunnel my-vm --remote-port 5432

隧道进程保持在前台运行。使用 Ctrl+C 停止它。你也可以通过沙箱 URL 而不是名称建立隧道：

langsmith sandbox tunnel \
  --url <SANDBOX_URL> \
  --remote-port 5432

对于你想在浏览器中打开或与团队共享的 HTTP 应用程序，请使用沙箱服务 URL。对于原始 TCP 协议或本地开发工具，请使用隧道。

设置 SSH 访问

使用 sandbox ssh-setup 配置标准 SSH 工具（如 ssh、scp、rsync 和 sftp）通过沙箱隧道进行连接。

langsmith sandbox ssh-setup my-vm
langsmith sandbox ssh-setup my-vm --identity ~/.ssh/id_ed25519.pub

该命令将你的 SSH 公钥上传到沙箱，在可用时获取沙箱主机密钥，将 Host sandbox-<name> 块写入 ~/.ssh/config，并将沙箱主机密钥写入 ~/.ssh/known_hosts_sandboxes。设置完成后，使用以下命令连接：

ssh sandbox-my-vm

沙箱镜像必须在端口 22 上运行 sshd。如果 sshd 未运行，ssh-setup 会发出警告，并且在你在沙箱内启动它之前，SSH 连接将无法工作。

ssh-setup 会修改本地 SSH 配置，并写入一个调用 langsmith sandbox tunnel 的 ProxyCommand。根据 CLI 的认证方式，生成的块可能包含凭据或凭据引用。仅在受信任的机器上运行它，并且不要提交或共享生成的 SSH 配置块。

命令参考

命令	描述
`langsmith sandbox snapshot list`	列出快照。
`langsmith sandbox snapshot build <name> --docker-image <image>`	从 Docker 镜像构建快照。
`langsmith sandbox snapshot capture <name> --box <sandbox>`	从运行中的沙箱捕获快照。
`langsmith sandbox snapshot get <snapshot-id>`	检查快照。
`langsmith sandbox snapshot wait <snapshot-id>`	等待快照就绪。
`langsmith sandbox snapshot delete <snapshot-id>`	删除快照。
`langsmith sandbox create <name> --snapshot-id <snapshot-id>`	从快照创建沙箱。
`langsmith sandbox list`	列出沙箱。
`langsmith sandbox get <name>`	检查沙箱。
`langsmith sandbox update <name>`	更新沙箱资源或代理配置。
`langsmith sandbox wait <name>`	等待沙箱就绪。
`langsmith sandbox start <name>`	启动已停止的沙箱。
`langsmith sandbox stop <name>`	停止运行中的沙箱，同时保留文件系统状态。
`langsmith sandbox delete <name>`	删除沙箱。
`langsmith sandbox exec <name> -- <command>`	在沙箱内运行一次性命令。
`langsmith sandbox console <name>`	在沙箱内打开交互式 shell。
`langsmith sandbox tunnel <name> --remote-port <port>`	将本地 TCP 端口转发到沙箱端口。
`langsmith sandbox ssh-setup <name>`	通过 `sandbox tunnel --stdio` 配置本地 SSH 访问。

连接这些文档到 Claude、VSCode 等，通过 MCP 获取实时答案。

在 GitHub 上编辑此页面或提交问题。

​安装与认证

​端到端工作流程

​管理快照

​管理沙箱

​代理配置

​运行命令

​打开交互式控制台

​隧道 TCP 端口

​设置 SSH 访问

​命令参考

安装与认证

端到端工作流程

管理快照

管理沙箱

代理配置

运行命令

打开交互式控制台

隧道 TCP 端口

设置 SSH 访问

命令参考