沙箱 CLI

从命令行创建、检查、连接沙箱，并向沙箱建立隧道。

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>"
export LANGSMITH_ENDPOINT="<LANGSMITH_ENDPOINT>"

LANGSMITH_ENDPOINT 默认为 https://api.smith.langchain.com（GCP US）。在 BYOC 上把它设为你的数据平面 URL，在自托管上设为你的实例 URL，或在其他 Cloud 区域上设为你所在区域的 API URL。

CLI 输出默认为人类可读的表格。加上 --format json 以获得可脚本化的输出：

langsmith --format json sandbox list

端到端工作流

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

langsmith sandbox create my-vm

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

create 会启动沙箱并在其报告 ready 时返回，因此下一条命令可以立即运行。没有单独的等待步骤。传入 --console 以在沙箱一起来就进入交互式 shell。

当你用完一个沙箱时，删除它：

langsmith sandbox delete my-vm

管理快照

从 Docker 镜像构建快照：

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

build 会把构建排入队列并立即返回快照的 status。轮询 langsmith sandbox snapshot get <SNAPSHOT_ID> 直到它报告 ready。--capacity 默认为 4gb，上限为 64gb。

对于私有镜像，先创建一个注册表（参阅私有注册表），然后用 --registry-id 传入它的 id：

langsmith sandbox snapshot build internal-python \
  --docker-image registry.example.com/internal/python:3.12 \
  --registry-id "$REGISTRY_ID"

从一个正在运行的沙箱捕获文件系统：

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

列出、检查和删除快照：

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

管理沙箱

用默认运行时创建一个沙箱。仅当你想从一个可复用的自定义快照启动时，才添加 --snapshot-id：

langsmith sandbox create my-vm --rootfs-capacity 8gb

用 --vcpus 和 --memory 设置沙箱大小。内存与 CPU 按每 vCPU 4 GiB 绑定，且必须保持在该目标的 50% 以内，因此一个 2-vCPU 沙箱接受 4 到 12 GiB。省略 --memory 则它遵循该比例。

langsmith sandbox create my-vm --vcpus 2 --memory 8gb

列出并检查沙箱：

langsmith sandbox list
langsmith sandbox get my-vm

停止一个沙箱以提前释放资源。它的文件系统被保留，且下一个 exec、console 或服务请求会自动唤醒它，因此没有需要运行的启动步骤：

langsmith sandbox stop my-vm
langsmith sandbox exec my-vm -- echo awake

更新资源或代理配置：

langsmith sandbox update my-vm --rootfs-capacity 16gb
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 把 stdout 打印到 stdout、把 stderr 打印到 stderr，并以沙箱命令的退出码退出。

打开交互式控制台

对由 PTY 支撑的交互式 shell 使用 sandbox console：

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

你可以把你本地的 SSH agent 转发进控制台会话：

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

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

以链接方式分享文件

铸造一个从沙箱下载单个文件、无需任何 LangSmith 凭据的链接，用于浏览器标签页或任何无法发送 API 密钥的东西：

langsmith sandbox generate-download-url my-vm --path /app/report.csv

若没有 --expires-in-seconds，链接永不过期。加上 --content-type 和 --content-disposition inline 以让浏览器渲染该文件而非下载它。此后不要修改该文件：链接固定到一个路径，而非内容的一份快照，所以后续的写入可能、也可能不会反映在该链接所提供的内容中。参阅沙箱下载链接。

隧道 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

TIP

对于你想在浏览器中打开或与队友分享的 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 连接不会工作。

WARNING

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 delete <snapshot-id>	删除一个快照。
langsmith sandbox create <name>	用默认运行时创建一个沙箱。
langsmith sandbox list	列出沙箱。
langsmith sandbox get <name>	检查一个沙箱。
langsmith sandbox update <name>	更新沙箱资源或代理配置。
langsmith sandbox stop <name>	在保留文件系统状态的同时停止一个正在运行的沙箱。后续的 exec、console 或服务请求会再次唤醒它。
langsmith sandbox delete <name>	删除一个沙箱。
langsmith sandbox exec <name> -- <command>	在沙箱内运行一次性命令。
langsmith sandbox console <name>	在沙箱内打开一个交互式 shell。
langsmith sandbox generate-download-url <name> --path <path>	铸造一个无需凭据下载单个沙箱文件的链接。
langsmith sandbox tunnel <name> --remote-port <port>	将一个本地 TCP 端口转发到一个沙箱端口。
langsmith sandbox ssh-setup <name>	通过 sandbox tunnel --stdio 配置本地 SSH 访问。

---