沙盒 CLI - Docs by LangChain中文

LangSmith CLI 包含沙盒命令，用于创建快照、启动沙盒、运行命令、打开交互式终端以及将 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>"

CLI 输出默认为 JSON 格式。对于 list 命令，添加 --format pretty 可获得人类可读的表格输出：

langsmith --format pretty sandbox list

端到端工作流

创建一个沙盒，然后在其中运行命令：

langsmith sandbox create my-vm \
  --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

对于私有镜像，请先创建一个仓库（参见私有仓库），然后通过 --registry-id 传递其 ID：

langsmith sandbox snapshot build internal-python \
  --docker-image registry.example.com/internal/python:3.12 \
  --registry-id "$REGISTRY_ID" \
  --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>

管理沙盒

使用默认运行时创建沙盒。仅当你希望从可重用的自定义快照启动时，才添加 --snapshot-id：

langsmith sandbox create my-vm \
  --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 支持的交互式终端：

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>`	使用默认运行时创建沙盒。
`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>`	在沙盒内打开交互式终端。
`langsmith sandbox tunnel <name> --remote-port <port>`	将本地 TCP 端口转发到沙盒端口。
`langsmith sandbox ssh-setup <name>`	通过 `sandbox tunnel --stdio` 配置本地 SSH 访问。

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

​安装与认证

​端到端工作流

​管理快照

​管理沙盒

​代理配置

​运行命令

​打开交互式控制台

​隧道 TCP 端口

​设置 SSH 访问

​命令参考

安装与认证

端到端工作流

管理快照

管理沙盒

代理配置

运行命令

打开交互式控制台

隧道 TCP 端口

设置 SSH 访问

命令参考