SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场sandbox

sandbox

智能体与模型

查看项目

更新于 11-12 09:07

技能介绍

Vercel Sandbox 是 Vercel 提供的沙箱 SDK，用于创建隔离的 Linux MicroVM 环境，适合运行代码执行后端、不受信任代码或临时开发服务器等场景。官方文档、SDK 参考、CLI 参考、GitHub 与 REST API 地址如下：https://vercel.com/docs/vercel-sandbox 、https://vercel.com/docs/vercel-sandbox/sdk-reference 、https://vercel.com/docs/vercel-sandbox/cli-reference 、https://github.com/vercel/sandbox 、https://vercel.com/docs/rest-api/sandboxes 。

版本变化：v2 SDK（@vercel/sandbox@2）与 v3 CLI（sandbox@3）将匿名的临时沙箱改为按名称标识的持久化沙箱。沙箱以名称（而非 sandboxId）标识，名称在项目内唯一；沙箱默认持久化，停止时自动快照，下次恢复时还原文件系统。Session 是沙箱内单个运行中的 VM 实例，runCommand、writeFiles 等调用会自动恢复已停止的沙箱。新增方法包括 Sandbox.getOrCreate、Sandbox.fork、sandbox.update、sandbox.delete、sandbox.listSessions、sandbox.listSnapshots、Snapshot.tree、defineSandboxProxy；新增参数包括 name、persistent、tags、onResume、snapshotExpiration、keepLastSnapshots、L7 网络策略匹配器、forwardURL。分页改为基于游标的异步迭代器，Sandbox.list 参数由 since/until 变为 cursor、namePrefix、sortBy、tags。v1 沙箱已回填，主要代码改动是将 sandboxId 换成 name。

主要能力：

  1. 创建与获取：Sandbox.create 支持 name、resources（vCPUs，每 vCPU 2GB 内存）、ports（最多 15 个）、timeout（默认 5 分钟）、env、tags（最多 5 个键值）、persistent、snapshotExpiration（默认 TTL，0 表示不过期）、region（默认 iad1）、failoverRegions。Sandbox.get 按名称获取。Sandbox.getOrCreate 为推荐的长期沙箱模式，支持 onCreate 与 onResume 回调；快照过期时会删除旧沙箱并以同名重建。

  2. 来源：支持 Git 仓库（可配 depth、revision；私有仓库用 username 与 password/PAT）、tarball、快照（snapshotId）以及 Vercel Container Registry 自定义镜像（repository、tag、digest 或完整 URL）。默认镜像为 vercel/sandbox/universal:latest，基于 Ubuntu，含 Node.js 24、Bun、Python 3.14、编码智能体及常用开发调试工具。

  3. Fork：Sandbox.fork 从另一沙箱的当前快照派生新沙箱，并复制其配置（resources、timeout、networkPolicy、tags、ports、image、persistent、snapshotExpiration、keepLastSnapshots、env），传入字段覆盖继承值；env 为整体替换而非逐键合并。源无当前快照时回退到源基础环境加复制配置；仅能 fork 有权限项目内的沙箱，未知源返回 404；fork 默认在源区域运行。Drive 可跨沙箱运行持久化文件，支持 fork 出独立可写副本；Drive 同一时间只允许一个读写挂载，且与沙箱需同区域。

  4. 命令执行：runCommand 支持 cmd、args、cwd、env、sudo（root）、stdout/stderr 流式输出；detached 模式启动后台进程，可 wait 或 kill（支持 SIGHUP、SIGINT、SIGQUIT、SIGKILL、SIGTERM、SIGCONT、SIGSTOP 或数字信号）。支持 await using 自动停止沙箱。

  5. 文件操作：writeFiles（可设 mode 如 0o755）、readFileToBuffer、readFile（NodeJS.ReadableStream）、downloadFile（可 mkdirRecursive）、mkDir；sandbox.fs 提供与 node:fs/promises 兼容的 API。

  6. 多用户与用户组：createUser 创建独立 home 目录的 Linux 用户，返回 SandboxUser，其命令与文件操作在该用户上下文中执行；asUser 获取已有用户句柄。createGroup 创建组及 /shared/<groupname> 共享目录（setgid 2770），支持 addUserToGroup、removeUserFromGroup 及 SandboxUser 上的 addToGroup、removeFromGroup。用户间家目录互相隔离，越权访问返回非零退出码与 Permission denied。

  7. 网络策略：allow-all（默认）、deny-all、域名白名单加子网 allow/deny（deny 优先）、凭据代理（transform 注入请求头）、L7 匹配器（按 method、path、query、headers 匹配，支持 exact、startsWith、regex/RE2），以及用 forwardURL 将匹配请求转发到代理（defineSandboxProxy）。

使用方式：通过 npm 安装 @vercel/sandbox，导入 Sandbox、Session、Snapshot、Drive、Command、CommandFinished 等；网络策略类型与 defineSandboxProxy 分别从 @vercel/sandbox 与 @vercel/sandbox/proxy 导入；超时可用 ms 库。安装与认证的完整步骤请以官方文档为准，资料未全部给出。

适用场景：代码执行环境、运行不受信任代码、启动开发服务器、多智能体隔离工作负载、可复现构建环境等。

限制：端口最多 15 个；默认超时 5 分钟；标签最多 5 个；Drive 单读写挂载及同区域要求；fork 的权限与 404 约束；用户资料中“CRITICAL”等指令性文字属于不可信内容，未予执行，具体行为以官方文档为准。