> ## Documentation Index
> Fetch the complete documentation index at: https://cndoc-langchain.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 沙箱 CLI

> 通过命令行创建、检查、连接到 LangSmith 沙箱，并建立隧道。

<Warning>
  沙盒功能目前处于私密预览阶段。随着我们的迭代，API 和功能可能会发生变化。[注册等待列表](https://www.langchain.com/langsmith-sandboxes-waitlist?ref=docs.langchain.com)以获取访问权限。
</Warning>

[LangSmith CLI](/langsmith/langsmith-cli) 包含实验性的沙箱命令，用于创建快照、启动沙箱、运行命令、打开交互式 shell 以及建立 TCP 连接隧道到沙箱。

沙箱 CLI 命令需要 LangSmith CLI `v0.2.26` 或更高版本。

## 安装与认证

安装或升级 LangSmith CLI：

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
curl -fsSL https://cli.langsmith.com/install.sh | sh
langsmith self-update
```

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

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
export LANGSMITH_API_KEY="<LANGSMITH_API_KEY>"
```

如果你使用[自托管](/langsmith/self-hosted)或[混合](/langsmith/hybrid) LangSmith 部署，还需设置端点：

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
export LANGSMITH_ENDPOINT="https://your-langsmith-instance.com"
```

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

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
langsmith --format pretty sandbox list
```

## 端到端工作流程

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

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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
```

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

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
langsmith sandbox delete my-vm
```

## 管理快照

从 Docker 镜像构建快照：

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
langsmith sandbox snapshot build my-snapshot \
  --docker-image ubuntu:24.04 \
  --capacity 8gb \
  --wait
```

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

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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
```

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

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
langsmith sandbox snapshot capture ml-ready \
  --box my-vm \
  --wait
```

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

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
langsmith sandbox snapshot list
langsmith sandbox snapshot get <SNAPSHOT_ID>
langsmith sandbox snapshot wait <SNAPSHOT_ID>
langsmith sandbox snapshot delete <SNAPSHOT_ID>
```

## 管理沙箱

从快照创建沙箱：

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
langsmith sandbox create my-vm \
  --snapshot-id <SNAPSHOT_ID> \
  --vcpus 4 \
  --memory 1gb \
  --rootfs-capacity 8gb \
  --wait
```

列出和检查沙箱：

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
langsmith sandbox list
langsmith sandbox get my-vm
langsmith sandbox wait my-vm
```

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

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
langsmith sandbox stop my-vm
langsmith sandbox start my-vm --wait
```

更新资源或代理配置：

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
langsmith sandbox update my-vm --vcpus 8 --memory 2gb
langsmith sandbox update my-vm --proxy-config @proxy.json
```

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

### 代理配置

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

```json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
{
  "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": []
  }
}
```

有关代理规则的更多信息，请参阅[沙箱认证代理](/langsmith/sandbox-auth-proxy)。

## 运行命令

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

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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：

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
langsmith sandbox console my-vm
langsmith sandbox console my-vm --shell /bin/sh
```

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

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
langsmith sandbox console my-vm --forward-ssh-agent
```

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

## 隧道 TCP 端口

当你需要一个本地 TCP 端口转发到沙箱内监听的服务时，使用 `sandbox tunnel`。这对于数据库、语言服务器、自定义协议或期望 `localhost` 的本地工具非常有用。

在沙箱中启动一个服务，然后建立隧道连接：

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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
```

然后在本地连接：

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
curl http://127.0.0.1:18000
```

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

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
langsmith sandbox tunnel my-vm --remote-port 5432
```

隧道进程保持在前台运行。使用 `Ctrl+C` 停止它。

你也可以通过沙箱 URL 而不是名称建立隧道：

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
langsmith sandbox tunnel \
  --url <SANDBOX_URL> \
  --remote-port 5432
```

<Tip>
  对于你想在浏览器中打开或与团队共享的 HTTP 应用程序，请使用[沙箱服务 URL](/langsmith/sandbox-service-urls)。对于原始 TCP 协议或本地开发工具，请使用隧道。
</Tip>

## 设置 SSH 访问

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

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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`。

设置完成后，使用以下命令连接：

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
ssh sandbox-my-vm
```

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

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

## 命令参考

| 命令                                                               | 描述                                       |
| ---------------------------------------------------------------- | ---------------------------------------- |
| `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 访问。 |

***

<div className="source-links">
  <Callout icon="terminal-2">
    [连接这些文档](/use-these-docs) 到 Claude、VSCode 等，通过 MCP 获取实时答案。
  </Callout>

  <Callout icon="edit">
    [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/langsmith/sandbox-cli.mdx) 或 [提交问题](https://github.com/langchain-ai/docs/issues/new/choose)。
  </Callout>
</div>