Nebutra/sandbox-runtime
GitHub: Nebutra/sandbox-runtime
面向 AI 工具执行的统一沙箱运行时，提供基于路由规则的本地与远程 provider 调度、健康检查及调试诊断能力。
Stars: 0 | Forks: 0
# @nebutra/sandbox-runtime
[@nebutra/sandbox-runtime](https://www.npmjs.com/package/%40nebutra%2Fsandbox-runtime) 的公开镜像，源自 [Nebutra/Nebutra-Sailor](https://github.com/Nebutra/Nebutra-Sailor/tree/main/packages/ai/sandbox-runtime)。
此仓库由 Nebutra Sailor monorepo 生成。包的发布版本是从 monorepo 中切割出来，并镜像到此处，以便于发现、独立克隆和接收贡献。
- 权威源：`Nebutra/Nebutra-Sailor` 中的 `packages/ai/sandbox-runtime`
- 包仓库：npm 和 GitHub Packages
- 贡献：在此处提交 issue 或 PR；维护者会将接受的更改移植回 monorepo 源包中
用于本地和远程执行 provider 的统一沙箱运行时路由器。
该包定义了 Nebutra 执行包使用的领域无关（domain-neutral）沙箱契约。它将请求路由到已配置的 provider，暴露 provider 的健康检查，并记录用于执行故障排除的调试事件。
## 安装
```
pnpm add @nebutra/sandbox-runtime
```
## 使用说明
```
import { SandboxRuntime } from "@nebutra/sandbox-runtime";
const runtime = SandboxRuntime.fromConfig();
const result = await runtime.exec({
cmd: "echo sandbox ok",
tenantId: "org_123",
threadId: "thread_123",
hints: {
networkAccess: false,
needsGpu: false,
},
});
```
## Provider
默认 provider：
| Provider | 行为 |
| --- | --- |
| `local_mac` | 调用位于 `SANDBOX_RUNTIME_LOCAL_URL` 或 `http://127.0.0.1:8020/api/v1/sandbox/exec` 的本地沙箱服务 |
| `remote_code` | 由 `SANDBOX_REMOTE_CODE_TOKEN` 控制的占位符 provider |
| `remote_gpu` | 由 `SANDBOX_REMOTE_GPU_TOKEN` 控制的占位符 provider |
| `remote_workspace` | 由 `SANDBOX_REMOTE_WORKSPACE_TOKEN` 控制的占位符 provider |
在宿主应用程序配置 provider SDK 之前，远程占位符会故意抛出异常。
## 路由
```
const runtime = SandboxRuntime.fromConfig({
routes: [
{ when: { needsGpu: true }, provider: "remote_gpu" },
{ when: { durationS: 30 }, provider: "remote_code" },
{ when: { needsGpu: false }, provider: "local_mac" },
],
});
const plan = runtime.plan({ cmd: "pnpm test", hints: { needsGpu: false } });
```
第一个匹配的静态路由生效。如果没有路由匹配，运行时会在 `local_mac` 已配置的情况下回退到它。
## API
| 导出 | 描述 |
| --- | --- |
| `SandboxRuntime` | Provider 注册表、规划器、执行器和诊断器（doctor） |
| `createLocalMacSandbox()` | 本地沙箱服务适配器 |
| `createRemotePlaceholder(id, envKey)` | 用于远程 provider 的显式占位符 |
| `sandboxDebugPath()` | 调试路径助手 |
| `readSandboxDebug(limit)` | 读取沙箱调试事件 |
| `ExecRequest` / `ExecResponse` | 执行请求和响应契约 |
| `Sandbox` / `SandboxHealth` | Provider 接口与健康状态结构 |
## 许可证
MIT
标签：AI工具执行, API网关, GNU通用公共许可证, MITM代理, Node.js, 暗色界面, 沙箱环境, 自动化攻击, 运行时引擎