编码Agent沙箱让Agent生成的命令和代码变更在受限的工作区中运行，在该工作区内，文件、进程、网络访问、密钥、日志以及审查制品均可被控制。实际目标并非假装任意生成的代码是无害的。目标是将Agent视为一个拥有一次性开发机器、明确边界、可观察执行过程以及投产前需经人工审批路径的不可信贡献者。
编码Agent沙箱需要隔离的内容
一个编码Agent在能够检查仓库、编辑文件、运行测试、安装依赖并提交补丁时，才变得有用。而这些操作也正是使环境具有风险的行为。一次提示注入导致的依赖安装、一条破坏性的Shell命令，或一个意外暴露的密钥，可能造成比一个错误文本答案更严重的损害。
围绕编码Agent可能接触的资源来设计沙箱：
| 层面 | 需要控制的内容 | 重要性 |
|---|---|---|
| 仓库检出 | 分支、提交SHA、写入范围、子模块、生成文件 | 防止Agent更改错误的代码库，或隐藏审核路径之外的变更。 |
| 文件系统 | 工作区根目录、挂载文件、忽略路径、输出目录 | 防止对主机文件、凭据、缓存和不相关项目进行广泛访问。 |
| Shell执行 | 允许的命令、工作目录、超时、输出捕获、审批门禁 | 赋予Agent足够的构建和测试能力，同时限制高风险操作。 |
| 包安装 | 注册表策略、锁定文件、锁定版本、缓存策略、安装日志 | 当Agent请求新依赖时，减少供应链的不确定性。 |
| 网络访问 | 默认出站、白名单、DNS行为、API目标、包镜像 | 有助于防止意外数据移动，并使外部调用可审查。 |
| 密钥 | 范围受限的凭据、短期令牌、脱敏处理、不默认使用生产密钥 | 防止Agent读取或泄露其不需要的凭据。 |
| 制品 | 测试报告、构建输出、截图、生成文件、日志 | 为审查者提供证据，而不只依赖Agent的摘要。 |
| 生命周期 | 暂停、恢复、快照、重置、清理、保留策略 | 使Agent运行可重复且可丢弃，而非长期存在的迷之机器。 |
将此表作为设计清单。无论你的沙箱是基于容器、虚拟机、微型虚拟机、托管云沙箱还是内部运行器，它都适用。具体的隔离层很重要，但围绕该层的操作控制同样重要。
运行Agent生成代码的参考工作流
最安全的编码Agent工作流看起来不像聊天机器人，而更像一个受控的拉取请求管道。
- 为任务创建一个全新的工作区。
- 在特定分支或提交处检出目标仓库。
- 给Agent一个狭窄的任务、测试命令和文件范围。
- 让Agent检查文件并提出计划。
- 自动运行低风险的只读命令。
- 对高风险命令要求审批或策略检查。
- 捕获每条命令、退出码、标准输出、标准错误、文件写入和生成的制品。
- 在沙箱内运行测试、类型检查、代码检查、构建或目标脚本。
- 导出补丁、差异、测试输出和制品包。
- 审查后重置或销毁工作区，除非有意保存了快照。
重要的细节是：沙箱不仅是执行代码的地方，也是证据记录器。审查者应能回答以下问题：检出了哪个仓库？发生了什么变更？运行了哪些命令？哪些失败了？哪些通过了？产生了哪些文件？联系了哪些外部资源？
对于简单的Agent，这可以实现为一个带有策略检查的动作队列。对于更强大的Agent，保持相同的边界，但使控制平面更明确：一个组件决定Agent允许请求什么，一个组件执行已批准的动作，一个组件记录运行过程。
用户任务
-> Agent 提出文件读取、编辑和命令建议
-> 策略层对每个动作进行分类
-> 沙箱执行已批准的动作
-> 捕获日志、差异和制品
-> 人工审查补丁，然后合并或部署
这种分离防止模型既是规划者，又是危险操作的最终权威。
命令执行前的安全检查点
首先假设生成的命令可能是错误的、过于宽泛的，或受仓库内容影响的。编码Agent可能从测试夹具、README、Issue正文、包脚本或网页中读取恶意指令。沙箱应使这些失败可见且可控。
在Shell执行之前，定义命令类别：
| 命令类别 | 示例 | 默认策略 |
|---|---|---|
| 只读检查 | pwd、ls、git status、rg、cat package.json |
通常允许并记录。 |
| 本地验证 | npm test、pytest、go test、cargo test |
允许，设置超时并捕获输出。 |
| 构建或生成 | npm run build、代码生成、文档生成 |
允许，当输出路径在预期范围内时。 |
| 依赖变更 | 包管理器安装、锁定文件更新 | 需要策略检查或审批。 |
| 网络命令 | 获取URL、调用API、克隆额外仓库 | 需要目标策略并记录日志。 |
| 破坏性命令 | 删除、强制重置、磁盘清理、广泛的chmod/chown | 阻止或需要明确的人工审批。 |
| 密钥访问 | 读取环境文件、凭据存储、部署配置 | 阻止，除非任务特定且范围受限。 |
这不需要完美的静态分析器。即使是简单的控制也有帮助：工作目录限制、明确的拒绝模式、命令超时、输出大小限制，以及针对改变依赖、接触凭据或联系外部主机的命令的审批提示。
文件系统边界也应同样具体。只挂载Agent所需的仓库和临时目录。避免挂载操作员的家目录、SSH密钥、云配置、包管理器凭据、浏览器配置文件或生产环境文件。如果需要缓存以提高速度，优先使用只读或任务范围的缓存，并明确保留策略。
如何处理包安装和网络访问
包安装是编码Agent沙箱中最困难的部分之一，因为它既有用又有风险。Agent需要重现构建和运行测试，但安装脚本可能执行代码、拉取传递依赖并联系外部基础设施。
对包操作使用更严格的策略：
- 优先使用基于锁定文件的安装，而非自由形式的依赖解析。
- 记录包管理器命令、注册表URL、包名称、版本和锁定文件变更。
- 尽可能通过批准的注册表或镜像路由依赖下载。
- 将新依赖添加视为需要审查的代码变更。
- 对于高风险工作流，阻止安装脚本，除非项目明确需要。
- 将依赖缓存与凭据和无关仓库分开。
网络出站也应同样对待。编码Agent可能需要访问互联网以获取包注册表、API文档、浏览器检查或集成测试。但这并不意味着需要无限制的出站访问。
至少，定义默认值：
| 网络问题 | 更安全的默认值 |
|---|---|
| 沙箱可以访问互联网吗？ | 除非任务需要，否则不允许。 |
| 它可以解析任意DNS名称吗？ | 限制或记录DNS和目标主机。 |
| 它可以调用生产API吗？ | 默认使用暂存端点或模拟服务。 |
| 它可以获取包依赖吗？ | 使用批准的注册表、镜像和锁定文件。 |
| 它可以上传文件或日志吗？ | 除非目标符合预期并经过审查，否则阻止。 |
不要将这些控制描述为对数据泄露或依赖妥协不可能发生的保证。更现实的声明是：策略、隔离、日志记录和审查减少了爆炸半径，并在补丁被信任之前使危险行为更容易被发现。
用于人工审查的差异、制品和日志
当沙箱产生一个紧凑的审查包，而不是冗长的聊天记录时，人工审查最有效。
对于每次运行，捕获：
- 用于检出的仓库URL、分支和提交SHA。
- 任务提示或问题摘要。
- 读取的文件和写入的文件。
- 每条命令、工作目录、开始时间、结束时间、退出码、标准输出和标准错误。
- 依赖安装命令和锁定文件变更。
- 测试、代码检查、类型检查和构建结果。
- 生成的制品，如截图、报告、覆盖率、二进制文件或预览URL。
- 最终差异，以标准补丁或拉取请求格式呈现。
审查者应首先检查差异，然后使用日志和制品来回答针对性问题。测试真的运行了吗？Agent是否修改了请求范围之外的代码？它是否添加了依赖？它是否重写了生成的文件？它是否调用了网络服务？它是否留下了大量或敏感的制品？
对于生产团队，使审查门控显式化：
- Agent可以提出补丁。
- 沙箱可以运行验证。
- 系统可以打开拉取请求。
- 人工或已批准的策略必须决定是否合并、部署或授予更广泛的权限。
对于包含基础设施、计费、认证、部署或客户数据路径的仓库，这个边界尤其重要。
Novita Agent沙箱的定位
Novita Agent沙箱 专为隔离、有状态的执行环境而设计，Agent可以在其中运行代码、安装依赖、访问文件、使用浏览器工作流，并在会话间保留执行状态。Agent沙箱概述 描述了三个核心构建块：用于隔离任务执行的沙箱、用于准备环境的模板，以及用于重用已配置状态的快照。
对于编码Agent工作流，这些原语自然地映射到受控的开发工作区：
| 编码Agent需求 | 沙箱模式 |
|---|---|
| 从已知环境开始 | 使用包含预期运行时和工具的模板。 |
| 在主机之外运行命令和测试 | 在沙箱特定的文件系统和运行时环境中执行。 |
| 重用已准备好的设置 | 在安装已批准的依赖或项目工具后保存快照。 |
| 调试长时间运行的Agent工作 | 当工作流需要连续性时，跨会话保留状态。 |
| 审查后清理 | 根据保留策略重置、停止或丢弃沙箱。 |
将产品使用和安全策略分开。Novita Agent沙箱可以为运行代码的Agent提供隔离的执行环境，但你的应用程序仍需定义仓库访问、命令策略、密钥范围、网络规则、制品保留和人工审批门禁。这些选择取决于你的威胁模型，并应在公开生产使用前由你的工程和安全负责人审查。
想要动手实践的开发者，还可以阅读Novita指南：使用Novita沙箱构建远程代码执行MCP服务器。产品文档，请从Novita Agent沙箱文档 和SDK与CLI安装指南 开始。
常见问题
编码Agent沙箱足以让生成的代码安全吗？
不是。沙箱只是一个控制层。你仍然需要范围受限的仓库访问、命令策略、依赖控制、网络限制、密钥处理、日志、制品审查，以及在合并或部署前的人工审批。
编码Agent应该拥有互联网访问权限吗？
只有当任务需要时才允许。许多代码审查、重构和测试工作流在依赖准备完毕后，无需一般互联网访问即可运行。当需要互联网访问时，记录目标，并优先使用白名单包注册表、文档站点、暂存API或模拟服务。
Agent应该获得生产密钥吗？
默认避免将生产密钥交给编码Agent。使用针对特定任务的范围受限、短期凭据，优先使用暂存服务，对日志进行脱敏处理，并除非有经过审查的理由，否则将密钥访问排除在仓库工作区之外。
在信任Agent补丁之前，应审查什么？
审查差异、变更的依赖、生成的文件、命令日志、测试结果、网络活动及任何制品。特别关注认证、授权、部署、计费、基础设施、数据访问和包管理变更。
何时应该重置沙箱？
每次任务后重置或销毁工作区，除非有意保存了快照。持久状态对长时间运行的工作流有用，但它应是一个经过深思熟虑的选择，并带有所有权、保留和清理规则。
