用途
该技能讲解如何把重负载工作从本地机器转移到 Vercel Sandbox。Vercel Sandbox 是可在数秒内创建的 Linux 微虚拟机（x86_64），用完即可删除，因而适合作为远程工作机：让繁重构建和长时间测试套件不占用本地笔记本，并让每个智能体或任务拥有独立的干净机器。
何时卸载、何时保留本地
适合卸载到沙箱的工作包括：完整测试套件（尤其是可分片时）；耗时数分钟或需要 Linux 的构建；同时进行的多个任务（每个任务或每个智能体一个沙箱）；任何占满本地磁盘的内容（大型构建树、多个工作树）。
适合保留在本地的工作包括：编辑、git、小型聚焦测试、类型检查和 lint、编排，以及任何需要本地凭据或沙箱不具备的硬件的工作。多个智能体共享一台机器时的推荐默认做法是：智能体在本地编辑并运行快速聚焦检查，所有重活交给各自的沙箱。
计划限制
Hobby、Pro、Enterprise 的最大 vCPU 分别为 4（8 GB）、8（16 GB）、32（64 GB）；最大会话时长分别为 45 分钟、24 小时、24 小时；并发沙箱数分别为 10、10,000、10,000。--vcpus 取 1 或不超过计划上限的偶数，默认 2。Hobby 每月仅含 5 小时 Active CPU，重度卸载实际上需要 Pro。运行中的沙箱按 Active CPU 和预置内存计费；快照按 GB-月收取快照存储费。
一次性准备基础快照
在每个新沙箱中安装工具链和依赖会浪费时间和费用。做法是：用默认镜像（Ubuntu、Node.js、Python、常用工具）创建构建器沙箱，安装固定版本工具链并构建基线树，然后制作快照（快照 ID 打印在 stderr），最后删除构建器（不影响快照）。基础快照中应包含项目固定的工具链版本、主分支在已知提交上的已安装已构建只读副本，以及任务会复用的小型辅助脚本。将快照 ID 保存在工具旁的文件中；--expiration 0 表示永不过期，会持续计费直到删除。工具链变化时构建新快照并删除旧快照。
按任务创建沙箱
用 vercel sandbox create 为每个任务创建非持久沙箱，指定快照、vCPU、超时和标签。按所有者和用途命名（如 exp-parser、exp-parser-2），避免并行智能体冲突；名称在项目内唯一，直到沙箱被删除。每个 vCPU 附带 2 GB 内存，这是获得更多内存的唯一方式；内存密集步骤可能被 Linux OOM killer 杀死。
生命周期与清理
沙箱默认持久：会话停止时文件系统会被快照以便日后恢复，并按快照存储计费。任务沙箱不需要此特性，因此创建时传 --non-persistent。--timeout 设置的是会话时长而非沙箱寿命，默认 5 分钟；超时后会话停止，其中所有运行内容（包括分离作业）被杀，非持久沙箱会丢失整个文件系统。任务完成用 vercel sandbox remove <name> 删除；stop 只结束当前会话。移除沙箱不会删除快照，因此基础快照在任务清理后仍存在。可用 vercel sandbox list --all --tag owner=<agent> 清理崩溃智能体留下的孤儿沙箱。
传入代码而不重装依赖
传输源码而非构建产物：把 git 已知的文件（已跟踪加未忽略的未跟踪文件）打包为一个 tar 包，复制过去并在旧树旁解压；然后把重目录（node_modules）从旧树移到新树，避免重装，再交换两者。每次变更后推送，只需数秒；然后运行幂等的准备步骤，只安装或重建变化的部分。平台特定产物应在沙箱内构建，不要把 macOS 二进制复制进 Linux 虚拟机。不要推送 .git 或依赖目录。
执行命令
将完整命令作为单个引号字符串传给 sh -c，避免本地 shell 提前展开变量和通配符。不要信任 vercel sandbox exec 的退出状态：即使远程命令失败它也返回 0；应在远程命令末尾输出 echo "exit=$?" 并读取该值，或使用会返回远程状态的 sbx exec。独立 Sandbox CLI 会透传远程退出码。超过一行的命令应写成脚本复制进去执行。
长作业应以分离方式启动并轮询，避免依赖本地 exec 连接或 exec 超时；会话超时仍然生效。
取回结果
让远程端写入紧凑结果文件（失败测试名摘要、退出码、JSON 报告），只把这些文件用 vercel sandbox copy 复制回来。copy 每次移动一个文件，目标必须是文件路径而非目录。源文件缺失时 copy 只打印错误而不失败，需事后检查本地文件是否存在。大型日志应远程压缩，仅在需要时获取。
分片与并行
按分片索引把慢速套件分到 N 个沙箱，并用测试运行器的分片功能或编排脚本同时运行各分片。每个任务使用自己的沙箱。并发应按预算而非 API 允许量设限，因为每个运行中的沙箱都花钱。大规模扇出受 vCPU 分配速度限制。
区分既有失败与新失败
远程套件通常有一些与你的改动无关的失败：环境差异、不稳定测试、主分支上已存在的失败。在同一沙箱中于未改动的基线上重跑失败测试，只有基线没有的失败才是你的问题。把已知仅环境相关的失败保持为简短列表。迭代期间运行聚焦检查，最终候选才跑完整套件。
认证与作用域
vercel sandbox 的令牌优先级为 --token、VERCEL_AUTH_TOKEN、VERCEL_TOKEN，然后是 vercel 登录会话；仅当这些都不可用时才回退到 VERCEL_OIDC_TOKEN。CI 或长期自动化应设置 VERCEL_TOKEN。独立 sandbox CLI 读取 VERCEL_AUTH_TOKEN 但不读 VERCEL_TOKEN，并会从当前目录加载 .env 文件。沙箱及其名称属于一个项目，脚本中应显式传 --scope 和 --project，否则从其他目录运行可能用到不同项目而看不到、复用不了或清理不了你的沙箱。
封装为小脚本
资料提供了一个名为 sbx 的 shell 封装脚本，提供 create、push、exec、get、put、rm、clean 子命令，减少常见错误并让智能体指令保持简短。典型会话为：创建沙箱、推送代码、运行测试、取回结果、删除沙箱。建议在封装脚本旁写一份简短的 SANDBOX.md 记录快照 ID、基础内容、准备步骤、测试运行方式和清理方式。