该 LangSmith CLI 包含用于创建快照、启动沙箱、运行命令、打开交互式 shell 以及将 TCP 连接隧道接入沙箱的沙箱命令。

Sandbox CLI 命令需要 LangSmith CLI v0.2.26 或更高版本。

安装与身份验证

安装或升级 LangSmith CLI：

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

使用 LangSmith API 密钥对 CLI 进行身份验证：

CLI 输出默认为 JSON。添加 --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

对于私有镜像仓库，请通过环境变量传递仓库凭据：

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
langsmith sandbox snapshot wait
langsmith sandbox snapshot delete 

管理沙箱

使用默认运行时创建沙箱。添加 --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

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

代理配置

使用 --proxy-config @proxy.json on create or update 配置沙箱身份验证代理。建议使用工作区密钥进行凭据注入，而非将原始密钥存储在本地文件中。

{
  "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，并以沙箱命令的退出码退出。

打开交互式控制台

使用 sandbox console 获取支持 PTY 的交互式 shell：

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 访问。

隧道传输 TCP 端口

使用 sandbox tunnel 当你需要将本地 TCP 端口转发到沙箱内部监听的服务时。这对于数据库、语言服务器、自定义协议或期望 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  \
  --remote-port 5432

设置 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

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

命令参考