沙箱
CubePlex 通过 OpenSandbox 在隔离的沙箱中执行由代理生成的代码。沙箱提供了一个安全环境，代理可以在其中运行代码、安装软件包并与文件交互，而不会影响你的主机基础设施。
沙箱配置分布在两个管理页面中：Admin > Sandbox（/admin/sandbox）用于配置策略，Admin > Sandbox Environment（/admin/sandbox-env）用于配置环境变量和密钥。
本页介绍组织级管理。面向用户的操作——从工作区设置中列出、重启和删除自己的沙箱——请参阅管理沙箱。
沙箱可运行的内容
代理通过单个基于 shell 的 execute 工具在沙箱中运行代码——它会执行 shell 命令、通过 heredoc 写入文件，以及运行脚本（例如 python script.py）。它并不局限于固定的编程语言列表。
实际可用的语言和工具取决于为组织配置的沙箱镜像（沙箱策略中的 default_image）。该镜像中安装的任何内容——Python、Node.js 以及其他运行时或 CLI 工具——都是代理可以使用的内容。如需支持额外语言或库，请配置一个包含它们的沙箱镜像。
沙箱策略
策略控制沙箱允许执行的操作，尤其是网络访问相关操作。
配置网络访问
- 前往 Admin > Sandbox。
- 设置默认网络操作：选择 Allow（默认允许所有出站流量）或 Deny（默认阻止所有出站流量）。
- 添加特定规则以覆盖默认设置：
- Allow 规则——允许访问特定主机或 IP 范围的流量（默认设置为 Deny 时很有用）。
- Deny 规则——阻止访问特定目标的流量（默认设置为 Allow 时很有用）。
- 点击 Save。
示例：严格限制的沙箱
将默认操作设置为 Deny，然后只为代理所需的主机添加允许规则：
| 规则 | 操作 | 目标 |
|---|---|---|
| 默认 | Deny | 所有出站流量 |
| 规则 1 | Allow | pypi.org, files.pythonhosted.org |
| 规则 2 | Allow | registry.npmjs.org |
| 规则 3 | Allow | api.your-internal-service.com |
这样可确保代理能够安装软件包并调用你的内部 API，但无法访问其他任何目标。
命令规则
除网络规则外，沙箱策略还可以匹配代理尝试执行的 shell 命令，并应用以下三种操作之一：
- Allow——允许匹配该模式的命令。
- Deny——阻止匹配该模式的命令。
- Confirm——暂停代理，并要求人工在命令运行前批准或拒绝该命令。
对于需要人工确认的敏感操作，请使用 Confirm；对于绝不能执行的命令，请使用 Deny。
每次沙箱运行也都具有执行超时限制：长时间运行的命令会被自动终止，避免卡住的进程无限期占用沙箱。
环境变量和密钥
你可以在运行时向沙箱注入环境变量和密钥。这样，代理代码便可访问 API 密钥、数据库 URL 或配置值，而无需将它们硬编码。
作用域级别
环境变量可以限定在三个级别：
| 作用域 | 可见范围 | 管理位置 |
|---|---|---|
| 组织 | 所有工作区、所有用户 | Admin > Sandbox Environment |
| 工作区 | 该工作区内的所有用户 | 工作区自身的设置 |
| 用户 | 仅限该工作区中该用户的沙箱会话 | 工作区自身的设置 |
当同一个变量名同时存在于多个作用域时，范围更窄的作用域优先：用户覆盖工作区，工作区覆盖组织。
Admin > Sandbox Environment 页面仅管理组织作用域的变量——它们会被注入到每个工作区的沙箱中。工作区和用户作用域变量需要从各自工作区内添加，而不是在此管理页面中添加。
添加组织环境变量
- 前往 Admin > Sandbox Environment。
- 点击 Add Variable。
- 输入变量名称和值。
- 若要存储凭据，请将其标记为 secret。密钥的处理方式与普通值截然不同（请参阅密钥如何不进入沙箱）——你还需要指定允许将密钥发送到哪些主机，以及可选的适用请求header 名称。
- 点击 Save。密钥的值会被加密，保存后不会再次显示。
密钥如何不进入沙箱
对于任何敏感信息——API 密钥、令牌、数据库密码——请使用密钥条目，而非普通变量。CubePlex 的设计确保真实密钥值永远不会存在于沙箱内，以防代理编写的代码（或其日志）泄露它。两类条目的行为不同：
- 普通变量（未标记为密钥）会以其字面值注入到沙箱环境中。请将其用于非敏感配置（Base URL、区域名称、功能开关）。代码可直接读取它们，它们也可能出现在输出和日志中。
- 密钥绝不会以真实值注入。沙箱接收的是不透明的占位符令牌（例如
cbxref_…）。你的代码使用该占位符的方式与使用真实密钥完全相同——例如，将它放入Authorizationheader。沙箱发起出站请求时，CubePlex 的出口代理会在网络边界将占位符替换为真实密钥，但仅在同时满足以下条件时才会替换：- 目标主机是你为该密钥允许的主机之一；并且
- 占位符出现在允许的 header 名称之一中（若已配置 header 名称）。
该设计带来的结果：
- 真实密钥永远不会存在于沙箱中。 代码、文件和执行日志只会看到占位符——因此密钥不会出现在代理输出或运行日志中。
- 替换在沙箱外部进行，由出口代理完成，因此密钥绝不会写入任何沙箱进程或日志。
- 静态加密。 密钥值存储在凭据保险库中，只有代理在请求时、针对已验证的沙箱和允许的主机，才由代理解密。
- 泄露的占位符没有价值。 它仅对自身沙箱及允许的主机有效，且会在运行结束时被撤销。
常见使用场景
- 供代理代码直接调用的外部服务的 API 密钥（不是通过 MCP 调用）。
- 用于数据分析任务的数据库连接字符串。
- 因工作区而异的功能开关或配置值。