内容
# 塔珀
> 开源 **AI 代理沙盒** — 在您自己的机器上安全地运行不受信任的、AI 生成的代码。由 Apple Containers 支持，具有 E2B 风格的 TypeScript SDK。
[](https://www.npmjs.com/package/@tupper/sdk)
[](https://github.com/lightbearco/tupper/actions/workflows/ci.yml)
[](LICENSE)
[](tsconfig.base.json)
[](https://bun.com)
**塔珀** 为 AI 代理提供了一个隔离的环境来执行代码、运行 shell 命令、读写文件 — 而不会使宿主面临风险。它是一个自我托管的、**平台无关的** 替代托管代码执行沙盒的方案，如 E2B、Daytona 和 Modal：相同的 E2B 风格的 SDK，但通过 Apple Containers 在 macOS 上运行在您自己的机器上（Linux 使用 Firecracker，Windows 使用 WSL）。
<img width="1774" height="887" src="https://github.com/user-attachments/assets/d0de061b-a8ff-4e8a-9168-0fd1ba8c09a9" />
> [!NOTE]
> 塔珀处于早期开发阶段。`@tupper/core`、`@tupper/container` 和 `@tupper/sdk` 功能正常；API 可能在 1.0 版本之前发生变化。
## 目录
- [功能](#功能)
- [要求](#要求)
- [安装](#安装)
- [快速入门](#快速入门)
- [软件包](#软件包)
- [架构](#架构)
- [沙盒方法比较](#沙盒方法比较)
- [常见问题](#常见问题)
- [文档](#文档)
- [路线图](#路线图)
- [贡献](#贡献)
- [许可证](#许可证)
## 功能
- **一个 SDK，适用于所有操作系统** — 编写一次代理代码；塔珀会自动为宿主选择合适的沙盒运行时（macOS 上的 Apple Containers，Linux 上的 Firecracker，Windows 上的 WSL）。新平台是即插即用的 — 后端会自行注册导入。
- **E2B 风格的 SDK** — `Sandbox.create()`、`commands.run()`、`files.*`，以及重新连接和生命周期控制。
- **原生 macOS 沙盒** — 通过 `container` CLI 使用 Apple Containers，无需 Docker 守护进程。
- **可在 Node 或 Bun 上运行** — 精简的核心（Zod 是其唯一的运行时依赖）；源代码仅使用 Node 内置模块，不会附带任何 `Bun.*` API，因此它在任一运行时上均可运行而无需修改。
- **代理框架就绪** — 为 deepagents 和 Mastra 提供即插即用的沙盒后端，以及 [Model Context Protocol](https://modelcontextprotocol.io) 服务器、CLI 和 HTTP API。
## 要求
- **macOS 26+**，并使用 Apple 的 [`container`](https://github.com/apple/container) CLI 作为默认后端（启动一次 `container system start` 即可）。
- **Node 18+** 或 **[Bun](https://bun.com) 1.1+** 来消费软件包。
## 安装
```bash
# Bun
bun add @tupper/sdk @tupper/container
# npm
npm install @tupper/sdk @tupper/container
```
在安装 SDK 的同时，为您的平台安装沙盒后端 — 它是一个可选的同级依赖（macOS 上为 `@tupper/container`）。
## 快速入门
```ts
import { Sandbox } from "@tupper/sdk";
const box = await Sandbox.create({ image: "docker.io/library/alpine:latest" });
try {
await box.files.write("/tmp/hi.txt", "hello");
const res = await box.commands.run("cat /tmp/hi.txt");
console.log(res.stdout); // "hello"
} finally {
await box.kill();
}
```
更多信息请参见 [入门](docs/getting-started.md) 和 [SDK 参考](docs/sdk.md)。
## 软件包
### 核心
| 软件包 | 版本 | 描述 |
| --- | --- | --- |
| [`@tupper/core`](packages/core) | [](https://www.npmjs.com/package/@tupper/core) | 与后端无关的沙盒抽象、共享类型、Zod 模式和动态后端解析。 |
### 后端
自行注册导入；`@tupper/core` 为宿主平台选择一个。
| 软件包 | 版本 | 描述 |
| --- | --- | --- |
| [`@tupper/container`](packages/container) | [](https://www.npmjs.com/package/@tupper/container) | Apple Containers（`container` CLI，macOS 26+）。 |
| [`@tupper/firecracker`](packages/firecracker) | [](https://www.npmjs.com/package/@tupper/firecracker) | 用于 Linux 的 Firecracker microVM（nerdctl / firecracker-containerd）。🧪 实验性。 |
| [`@tupper/wsl`](packages/wsl) | — | 用于 Windows 的 WSL。🔜 计划中。 |
### 前端
驱动沙盒的方式，均基于 `@tupper/sdk` 构建。
| 软件包 | 版本 | 描述 |
| --- | --- | --- |
| [`@tupper/sdk`](packages/sdk) | [](https://www.npmjs.com/package/@tupper/sdk) | 类似 E2B 的 `Sandbox` 接口 — 核心编程 API。 |
| [`@tupper/cli`](packages/cli) | [](https://www.npmjs.com/package/@tupper/cli) | `tupper` 命令行接口。 |
| [`@tupper/api`](packages/api) | [](https://www.npmjs.com/package/@tupper/api) | SDK 上的 HTTP API（Hono）。 |
| [`@tupper/mcp`](packages/mcp) | [](https://www.npmjs.com/package/@tupper/mcp) | Model Context Protocol 服务器。 |
### 集成
代理框架的即插即用沙盒后端。
| 软件包 | 版本 | 描述 |
| --- | --- | --- |
| [`@tupper/deepagents`](packages/deepagents) | [](https://www.npmjs.com/package/@tupper/deepagents) | LangChain deepagents 沙盒后端。 |
| [`@tupper/mastra`](packages/mastra) | [](https://www.npmjs.com/package/@tupper/mastra) | Mastra `WorkspaceSandbox` 后端。 |
## 架构
```mermaid
flowchart TB
subgraph backends["后端 — 自行注册导入"]
container["@tupper/container<br/>Apple Containers ✅"]
firecracker["@tupper/firecracker<br/>Linux 🧪"]
wsl["@tupper/wsl<br/>Windows 🔜"]
end
core["@tupper/core<br/>抽象 · 类型 · 模式 · 运行时后端解析"]
sdk["@tupper/sdk<br/>类似 E2B 的 Sandbox 接口"]
subgraph consumers["消费者"]
cli["@tupper/cli"]
api["@tupper/api"]
mcp["@tupper/mcp"]
adapters["@tupper/deepagents · mastra"]
end
container -. registers .-> core
firecracker -. registers .-> core
wsl -. registers .-> core
sdk --> core
cli --> sdk
api --> sdk
mcp --> sdk
adapters --> sdk
```
`@tupper/core` 永远不会静态导入后端 — 它在运行时从宿主平台选择一个（`darwin → @tupper/container`，`linux → @tupper/firecracker`，`win32 → @tupper/wsl`），后端会自行注册导入，因此添加平台是即插即用的。你可以覆盖选择，使用 `Sandbox.create({ backend: "@tupper/firecracker" })`。详情请参见 [架构](docs/architecture.md)。
## 沙盒方法比较
沙盒在启动速度和隔离强度之间进行权衡，它们在是否提供完整的操作系统镜像或仅限于主机进程方面有所不同。塔珀不是像 E2B、Daytona 或 Modal 那样的托管服务 — 它在本地运行 — 因此公平的比较是按隔离方法进行，每个工具都按其所属层级进行划分：
| 方法 | OCI 镜像 | 内核 | 边界 | 启动（类别） | 示例 |
| --- | --- | --- | --- | --- | --- |
| 进程沙盒 | ❌ | 共享 | 主机内核 | ~instant（µs–ms） | macOS Seatbelt · Linux seccomp / Landlock · Windows AppContainer |
| 容器，共享内核 | ✅ | 共享 | 主机内核 | ~数十毫秒 | Docker · Daytona |
| **microVM / 每个容器一个 VM** | ✅ | 独有 | 硬件 VM | ~100–300 毫秒 | Firecracker（E2B）· **Apple Containers（塔珀）** · WSL2 · gVisor（Modal）† |
塔珀位于顶层 — 每个沙盒都有自己的**内核**，运行一个**完整的 OCI 镜像** — 但**在您自己的机器上**，使用操作系统的原生虚拟化（目前为 Apple 的 Virtualization.framework；计划使用 Firecracker/KVM 和 WSL2/Hyper-V）。
<sub>† gVisor 是一个用户空间内核，位于容器和完整 VM 之间。启动时间是底层运行时的发布数字（不是塔珀基准），并根据镜像、配置和主机而有所不同。来源：[Apple Containers](https://thenewstack.io/apple-containers-on-macos-a-technical-comparison-with-docker/) · [Firecracker](https://firecracker-microvm.github.io/) · [E2B & Daytona](https://www.zenml.io/blog/e2b-vs-daytona) · [Modal](https://modal.com/docs/guide/cold-start) · [Windows Sandbox](https://learn.microsoft.com/en-us/windows/security/application-security/application-isolation/windows-sandbox/)</sub>
## 常见问题
### 什么是 AI 代理沙盒？
一个隔离的环境，允许 LLM 代理执行代码和 shell 命令，无需访问您的主机 — 从而限制了不受信任或 AI 生成的代码的破坏范围，使失控的代理无法读取您的文件、访问您的网络或破坏您的系统。
### 塔珀与 E2B、Daytona 或 Modal 等托管沙盒有何不同？
这些服务在云中运行代理代码并按使用量计费。塔珀提供类似的 SDK，但在您自己的机器上运行沙盒 — 无需云账户、无沙盒网络延迟，您的代码也不会离开您的基础设施。它处于早期阶段，设计为单主机。
### 塔珀需要 Docker 吗？
不。在 macOS 上，塔珀使用 Apple 原生的 [`container`](https://github.com/apple/container) 运行时 — 无需 Docker 守护进程。它可以运行任何 Linux OCI 镜像，因此您的代理可以使用 Python、Node.js、Go 等。
### 我可以将塔珀与 deepagents 或 Mastra 一起使用吗？
是的 — [`@tupper/deepagents`](packages/deepagents) 和 [`@tupper/mastra`](packages/mastra) 为这些框架提供了现成的沙盒后端。对于任何其他客户端，[`@tupper/mcp`](packages/mcp) 通过 [Model Context Protocol](https://modelcontextprotocol.io) 公开沙盒。
## 文档
- [入门](docs/getting-started.md) — 先决条件、安装、您的第一个沙盒。
- [SDK 参考](docs/sdk.md) — `@tupper/sdk` 的 `Sandbox` API。
- [架构](docs/architecture.md) — 分层和运行时后端解析。
## 路线图
- **可用** — `@tupper/core`、`@tupper/container`（macOS）、`@tupper/sdk`、`@tupper/firecracker`（Linux，实验性）、`@tupper/deepagents`、`@tupper/mastra`、`@tupper/cli`、`@tupper/api`、`@tupper/mcp`。✅
- **计划中** — `@tupper/wsl`（Windows）。
## 贡献
欢迎贡献！请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 和我们的 [行为准则](CODE_OF_CONDUCT.md)。发现漏洞？请遵循我们的 [安全策略](SECURITY.md)。
```bash
git clone https://github.com/lightbearco/tupper.git
cd tupper
bun install
bun test
```
## 许可证
[MIT](LICENSE) © 塔珀贡献者
---
<sub>**关键词：** AI 代理沙盒 · 沙盒代码执行 · 代码解释器 · 运行不受信任的代码 · E2B 替代品 · Apple Containers · Firecracker · WSL · LLM 代理运行时 · 自托管沙盒 · TypeScript</sub>
连接信息
猜你喜欢
暂无推荐服务器