一个安全、持久的 AI 智能体运行时，利用 WebAssembly 沙箱隔离执行不可信代码，提供 CPU、内存、超时等精细化资源控制与权限管理。
项目概述#
Capsule 是一个专为 AI 智能体设计的任务运行时环境，核心解决 AI 应用中执行不可信或第三方代码的安全性问题。通过 WebAssembly (Wasm) 实现跨平台隔离，支持 Python 3.13+ 和 Node.js 22+。
核心能力#
安全隔离
- 每个任务在独立的 WebAssembly 沙箱中运行，与主机系统完全隔离
- 文件系统访问控制：仅允许访问白名单目录 (
allowed_files) - 网络访问控制：仅允许访问白名单域名 (
allowed_hosts) - 环境变量控制：选择性暴露环境变量
资源控制
- CPU 限制：通过 Wasm Fuel 机制计量，支持 LOW/MEDIUM/HIGH/CUSTOM 级别
- 内存限制：可配置每个任务的内存上限（如 "512MB", "2GB"）
- 超时控制：可配置任务最大执行时间（如 "30s", "5m", "1h"）
容错与可观测性
- 自动重试：任务失败时自动重试（可配置重试次数）
- 生命周期跟踪：监控任务状态（运行中、已完成、失败）
- 结构化输出：JSON 格式的任务执行结果和元数据
技术架构#
基于 Rust (76.7%) 构建核心运行时，TypeScript (15.6%) 和 Python (7.1%) 提供 SDK 支持。
核心组件
- capsule-core：基于 Rust 和 Wasmtime 的核心运行时
- capsule-cli：命令行接口 (
capsule run,capsule build) - capsule-sdk：Python 和 TypeScript 开发工具包
- capsule-wit：WebAssembly 接口类型定义
关键技术
- Runtime: Wasmtime (WebAssembly 运行时), WASI (系统接口)
- Compilation: componentize-py (Python 转 Wasm), jco (JS 转 Wasm)
安装与快速开始#
Python
pip install capsule-run
Node.js
npm install -g @capsule-run/cli
npm install @capsule-run/sdk
示例代码 (Python)
from capsule import task
@task(name="main", compute="LOW", ram="64MB")
def main() -> str:
return "Hello from Capsule!"
在现有代码中集成
from capsule import run
result = await run(file="./hello.py", args=[])
print(f"Task completed: {result['result']}")
配置选项#
| 参数 | 描述 | 示例 |
|---|---|---|
| name | 任务标识符 | "process_data" |
| compute | CPU 分配级别 | "HIGH" |
| ram | 内存限制 | "512MB" |
| timeout | 最大执行时间 | "30s" |
| max_retries | 失败重试次数 | 3 |
| allowed_files | 可访问文件夹 | ["./data"] |
| allowed_hosts | 可访问域名 | ["api.openai.com"] |
支持 capsule.toml 项目配置文件设置默认值。
CLI 命令#
capsule run <file>: 执行任务脚本capsule build <file>: AOT 预编译任务--verbose: 显示详细日志--json: 输出 JSON 格式结果
兼容性说明#
- Python: 仅支持纯 Python 包和标准库模块，不支持 C 扩展（如 numpy、pandas）
- TypeScript/JavaScript: 支持 npm 包和 ES 模块
适用场景#
- AI Agent 工具调用与编排
- 执行不可信或用户提供的代码
- 文件数据处理（CSV、图片、数据集）
- 受限网络访问的 API 调用
- 资源限制测试
响应格式#
{
"success": true,
"result": "<task return value>",
"execution": {
"task_name": "analyze_data",
"duration_ms": 1523,
"retries": 0,
"fuel_consumed": 45000
}
}
当前版本：v0.6.2 | 许可证：Apache-2.0