tupper

tupper 快速入门

给 AI Agent 一个真正的沙箱 —— 不是进程隔离，是微虚拟机。tupper 让 AI 生成的代码在自己的内核里运行，碰不到你的系统。

这是什么？适合谁？

tupper 是一个面向 AI Agent 的开源代码沙箱，由 sheikhuzairhussain 开发。它的核心思路很直接：AI Agent 生成的代码不可信，那就在一个隔离的微型虚拟机里运行它。

和常见的进程级沙箱（Node.js vm 模块、Python exec）不同，tupper 使用操作系统原生的虚拟化能力 —— macOS 上用 Apple Containers（Virtualization.framework），Linux 上用 Firecracker 微虚拟机，Windows 上计划使用 WSL2。每个沙箱实例拥有自己的 Linux 内核，可以运行完整的 OCI 镜像（Alpine、Ubuntu 等），Agent 在里面 pip install、npm install、读写文件都碰不到宿主系统。

它提供了一套和 E2B 兼容风格的 TypeScript SDK，但所有沙箱都在你自己的机器上运行——不需要云账号，不需要按次付费，代码不出你的基础设施。

核心特点：

• 微虚拟机隔离：每个沙箱拥有独立内核，不是进程级隔离，安全边界是硬件虚拟化级别
• E2B 风格 SDK：Sandbox.create()、commands.run()、files.* 等熟悉的 API，从 E2B 迁移零学习成本
• 完整 OCI 镜像支持：Agent 可以在沙箱里 apt-get、pip install，和真实 Linux 环境完全一致
• 多前端接入：TypeScript SDK、CLI 命令行、HTTP API、MCP Server 四种方式驱动沙箱
• 框架集成：提供 deepagents 和 Mastra 的即用沙箱后端
• 开源免费：MIT 协议，代码完全开放

适合谁？三类人最受益：一是已经在用 E2B / Daytona 的开发者，想省云费用把沙箱跑在本地；二是需要高安全性代码执行的场景（AI Agent 生成的未知代码、用户提交的脚本）；三是对数据不出境有合规要求的企业，tupper 可以完全离线运行。不适合：只有 Windows 机器的用户（Windows 支持仍在计划中），或需要多机分布式沙箱集群的场景（tupper 是单机方案）。

⚠️ tupper 目前处于早期开发阶段（pre-1.0），API 可能在正式版前变动。macOS 后端稳定可用，Linux 后端标记为实验性，Windows 后端计划中。

准备工作

• 系统要求：macOS 26+（稳定）；Linux（实验性，需 Firecracker）；Windows（计划中，WSL2）
• Apple Containers：macOS 需先安装 Apple 的 container CLI —— 访问 github.com/apple/container 了解安装方式，安装后运行 container system start 启动容器运行时
• 运行时：Node.js 18+ 或 Bun 1.1+
• 网络要求：首次使用需从 npm 下载包（@tupper/sdk + @tupper/container），之后可完全离线使用
• 付费要求：完全免费，无需任何注册或账号
• 可选准备：安装 Bun（curl -fsSL https://bun.sh/install | bash），Bun 构建的 tupper 启动更快

3 步快速上手

第 1 步：安装 tupper

# 使用 Bun（推荐，速度更快）
bun add @tupper/sdk @tupper/container

# 或使用 npm
npm install @tupper/sdk @tupper/container

@tupper/container 是 macOS 的沙箱后端（基于 Apple Containers），作为可选 peer dependency 安装。Linux 用户换装 @tupper/firecracker（实验性）。

第 2 步：启动沙箱并运行代码

创建 hello-tupper.ts：

import { Sandbox } from "@tupper/sdk";

const box = await Sandbox.create({
  image: "docker.io/library/alpine:latest"
});

try {
  // 写入文件
  await box.files.write("/tmp/hello.txt", "Hello from sandbox!");

  // 执行命令
  const result = await box.commands.run("cat /tmp/hello.txt");
  console.log(result.stdout); // "Hello from sandbox!"

  // 在沙箱里安装 Python 包
  await box.commands.run("apk add python3 && pip install numpy");
} finally {
  await box.kill(); // 用完销毁
}

bun run hello-tupper.ts

沙箱启动约 100-300ms（Apple Containers 级别），比 Docker 快，比进程级沙箱略慢但隔离强度高一个数量级。

第 3 步：接入 AI Agent

tupper 提供 MCP Server，任何支持 MCP 协议的 AI Agent（Claude Code、Cursor、Codex CLI 等）都能直接使用：

# 启动 MCP Server
npx @tupper/mcp

在 Claude Code 的 MCP 配置中添加：

{
  "mcpServers": {
    "tupper": {
      "command": "npx",
      "args": ["@tupper/mcp"]
    }
  }
}

配置完成后，Agent 的代码执行请求会自动路由到 tupper 沙箱。你也可以用 CLI 手动管理：

# CLI 创建沙箱
npx @tupper/cli sandbox create --image alpine

# 列出运行中的沙箱
npx @tupper/cli sandbox list

# 销毁沙箱
npx @tupper/cli sandbox kill <id>

常见踩坑

1. macOS 26+ 硬要求——tupper 稳定版后端需要最新 macOS，检查你的系统版本：sw_vers -productVersion。版本不够只能等 Apple 推送更新或用 Linux 实验后端
2. container CLI 未启动——运行前必须 container system start，否则会报 “container daemon not running”
3. 沙箱启动慢——首次拉取 OCI 镜像需要下载（Alpine 约 5MB），之后从本地缓存秒启
4. 沙箱内网络受限——默认沙箱有独立网络栈，需要外网的话要在创建时配置网络策略
5. 文件不互通——沙箱内的文件系统和宿主机完全隔离，Agent 写的文件在沙箱销毁后消失，如需持久化用 box.files.download() 导出
6. Linux 后端不稳定——@tupper/firecracker 标记为实验性，生产环境建议用 macOS
7. Windows 尚不支持——WSL 后端在路线图中但未发布，Windows 用户目前无法使用

初级用法

1. 默认沙箱模式：Sandbox.create() 不指定后端，tupper 自动根据当前 OS 选择 —— macOS → Apple Containers，Linux → Firecracker
2. 指定镜像：传入 image 参数选择 OCI 镜像（alpine:latest 最小最快，ubuntu:latest 包更全）
3. 文件操作：box.files.read()、box.files.write()、box.files.exists() 读写沙箱内文件
4. 命令执行：box.commands.run("ls -la") 执行任意 shell 命令，返回 stdout/stderr/exitCode
5. 生命周期管理：box.kill() 销毁沙箱释放资源；box.reconnect() 断线重连

高级玩法

1. 自定义后端选择：Sandbox.create({ backend: "@tupper/firecracker" }) 覆盖自动检测，在 macOS 上也用 Firecracker
2. 多沙箱并行：同时创建多个沙箱，Agent A 用 Python 环境，Agent B 用 Node.js 环境，互不干扰
3. 持久化卷挂载：通过 volumes 参数将宿主机目录挂载进沙箱，Agent 修改的内容实时回写
4. HTTP API 远程驱动：启动 @tupper/api 后可通过 REST API 远程管理沙箱，适合 Agent 在另一台机器上的场景
5. 自定义 OCI 镜像：构建包含预装依赖的镜像（pip install torch 等），Agent 进入即用，省去重复安装时间
6. 与 E2B 混合使用：SDK API 兼容 E2B，本地开发用 tupper（免费），CI/生产用 E2B（弹性），切换只改一行 import

小技巧

1. 用 Alpine 镜像做沙箱基础镜像 —— 体积小（~5MB），启动快，足以覆盖大多数 Agent 代码执行需求
2. 预构建一个 “AI-ready” 镜像：FROM alpine RUN apk add python3 py3-pip nodejs npm，存为本地镜像缓存，每次创建秒级启动
3. 在 CI 配置中将 @tupper/sdk 加入可选依赖，开发环境走 tupper 本地沙箱，CI 环境自动降级为 E2B 云后端
4. Agent 执行前用 box.commands.run("whoami && uname -a") 确认沙箱环境符合预期
5. 定期 docker system prune（如有 Docker）或清理 OCI 镜像缓存，避免旧镜像堆积占用磁盘
6. 为不同项目创建不同的沙箱配置模板（JSON/YAML），团队共享，确保一致的隔离策略

常见问题 FAQ

Q1: tupper 和 Docker 沙箱有什么区别？

tupper 使用操作系统原生虚拟化（Apple Containers / Firecracker），每个沙箱有独立内核，隔离级别高于 Docker 的共享内核容器。启动速度接近 Docker（100-300ms vs 几十 ms），安全边界强一个数量级。信息来源：tupper README - How sandboxing compares

Q2: tupper 和 E2B 有什么区别？

E2B 是云端的沙箱服务，按使用量付费，沙箱跑在 E2B 的服务器上。tupper 提供几乎相同的 SDK 体验（API 兼容），但沙箱跑在你自己的机器上，完全免费且代码不出本地。tupper 更适合开发和小规模使用，E2B 更适合需要弹性扩展的生产环境。信息来源：tupper README

Q3: tupper 收费吗？

完全免费开源（MIT License）。所有包在 npm 上可免费安装，本地运行无任何云服务依赖。信息来源：tupper GitHub LICENSE

Q4: tupper 能防止恶意代码吗？

是的，而且防护等级很高。每个沙箱运行在独立的微虚拟机中，拥有自己的内核，即使 Agent 生成的代码试图 rm -rf /、fork 炸弹、内核漏洞利用，影响范围也仅限于沙箱内部。这是硬件虚拟化级别的隔离，不是进程级别的。信息来源：tupper README - Architecture

Q5: 我只能用 Claude Code 接入 tupper 吗？

不只。tupper 提供四种接入方式：TypeScript SDK（任何 Node.js/Bun 应用）、MCP Server（任何支持 MCP 协议的 Agent）、CLI（命令行脚本）、HTTP API（远程调用）。Agent 框架方面，已提供 LangChain deepagents 和 Mastra 的即用后端。信息来源：tupper README - Packages

Q6: Windows 用户能用吗？

目前不能。tupper 的 macOS 后端已稳定，Linux 后端（Firecracker）实验性可用，Windows 的 WSL2 后端在路线图中。Windows 用户可以关注 GitHub 仓库的更新。信息来源：tupper README - Roadmap