Sandbank

为什么选择 Sandbank?

import { createProvider } from '@sandbank.dev/core'
import { SandbankCloudAdapter } from '@sandbank.dev/cloud'
const provider = createProvider(new SandbankCloudAdapter({
 apiToken: process.env.SANDBANK_API_TOKEN,
}))
const sandbox = await provider.create({ image: 'node:22' })
const result = await sandbox.exec('echo "Hello from the sandbox"')
console.log(result.stdout) // Hello from the sandbox
await provider.destroy(sandbox.id)

架构

┌──────────────────────────────────────────────────────┐
│ 你的应用 / AI Agent / 第三方调用方 │
├──────────────────────────────────────────────────────┤
│ sandbank Workspace Agent Harness │
│ AgentSupervisor policy / memory / tool use │
│ Provider Scheduler 多后端计算调度与同步 │
│ @sandbank.dev/workspace 持久 Workspace 与 Checkpoint │
├──────────────────────────────────────────────────────┤
│ @sandbank.dev/core 底层 Provider SDK │
│ @sandbank.dev/skills Skill 注册表与注入 │
│ @sandbank.dev/agent 沙箱内 Agent 客户端 │
│ @sandbank.dev/relay 多 Agent 通信中枢 │
├──────────────────────────────────────────────────────┤
│ @sandbank.dev/cloud @sandbank.dev/boxlite @sandbank.dev/e2b │
│ @sandbank.dev/daytona @sandbank.dev/flyio @sandbank.dev/cloudflare│
│ Provider 适配器(计算) │
├──────────────────────────────────────────────────────┤
│ @sandbank.dev/db9 Service Adapter(数据) │
├──────────────────────────────────────────────────────┤
│ Sandbank Cloud (托管 BoxLite) BoxLite (自托管 Docker) │
│ E2B Cloud Sandboxes Daytona Fly.io Machines Cloudflare Workers │
│ db9.ai (PostgreSQL) │
└──────────────────────────────────────────────────────┘

包一览

Provider 支持情况

基础操作

扩展能力

Provider 特性对比

多 Agent 会话

import { createSession } from '@sandbank.dev/core'
const session = await createSession({
 provider,
 relay: { type: 'memory' },
})
// 在隔离沙箱中启动 Agent
const architect = await session.spawn('architect', {
 image: 'node:22',
 env: { ROLE: 'architect' },
})
const developer = await session.spawn('developer', {
 image: 'node:22',
 env: { ROLE: 'developer' },
})
// 共享上下文 — 所有 Agent 均可读写
await session.context.set('spec', { endpoints: ['/users', '/posts'] })
// 等待所有 Agent 完成
await session.waitForAll()
await session.close()

import { connect } from '@sandbank.dev/agent'
const session = await connect() // 自动读取 SANDBANK_* 环境变量
session.on('message', async (msg) => {
 if (msg.type === 'task') {
 // 执行任务...
 await session.send(msg.from, 'done', result)
 }
})
await session.complete({ status: 'success', summary: '完成了 5 个 API 端点' })

Workspace Agent Harness

Provider-Neutral Workspaces(跨 Provider Workspace)

import {
 MemoryWorkspaceAdapter,
 materializeWorkspaceToSandbox,
 syncWorkspaceFromSandbox,
} from '@sandbank.dev/workspace'
const workspace = new MemoryWorkspaceAdapter()
await workspace.write('/workspace/task.md', 'ship it')
const sandbox = await provider.create({ image: 'node:22' })
await materializeWorkspaceToSandbox(workspace, sandbox, {
 workspacePath: '/workspace',
 sandboxPath: '/workspace',
})
await sandbox.exec('echo done > /workspace/result.txt')
await syncWorkspaceFromSandbox(workspace, sandbox, {
 workspacePath: '/workspace',
 sandboxPath: '/workspace',
 deleteMissing: true,
 checkpointLabel: 'after provider run',
})

Provider Scheduler 与 Preflight

import {
 preflightWorkspaceSandboxTask,
 runWorkspaceSandboxTask,
} from 'sandbank'
const taskConfig = {
 workspace,
 providers: [
 { provider: sandbankCloudProvider, capabilities: ['runtime.python', 'codex.exec'], priority: 30 },
 { provider: e2bProvider, capabilities: ['runtime.python'], priority: 10 },
 { provider: boxliteProvider, capabilities: ['runtime.python'] },
 ],
 task: { kind: 'python' as const, path: '/workspace/generated/task.py', image: 'python-agent' },
 imageCatalog: {
 'python-agent': {
 default: 'python:3.12',
 'sandbank-cloud': 'python:3.12-slim',
 e2b: 'e2b-python-template',
 boxlite: 'python:3.12-slim',
 },
 },
 preflight: { runtime: true },
}
const preflight = await preflightWorkspaceSandboxTask(taskConfig)
if (!preflight.ok) throw new Error(preflight.errors.join('; '))
await runWorkspaceSandboxTask({
 ...taskConfig,
 consistency: { mode: 'branch-merge', conflictResolution: 'keep-both' },
 preflight: false,
})

Agent Tool Use

import {
 AgentSupervisor,
 ToolUseRegistry,
 createCloudflareResourceTool,
 createSearchCodeRunTool,
 createSandboxPythonTool,
} from 'sandbank'
const registry = new ToolUseRegistry()
 .register(createCloudflareResourceTool('read', async input => {
 // 这里可以连接 Cloudflare D1/KV/R2 等 bindings 或 API。
 return { ok: true, resource: input.resource }
 }))
 .register(createSearchCodeRunTool({
 search: {
 provider: 'perplexity',
 search: async query => searchProvider.search(query),
 fetchJson: async url => searchProvider.fetchJson(url),
 },
 }))
 .register(createSandboxPythonTool())
const supervisor = new AgentSupervisor({
 agentId: 'agent-a',
 workspace,
 modelId: 'deepseek-v4-pro',
 toolUse: {
 registry,
 dynamicWorker,
 sandboxProviders: [
 { provider: sandbankCloudProvider, capabilities: ['runtime.python', 'codex.exec'] },
 { provider: e2bProvider, capabilities: ['runtime.python'] },
 { provider: boxliteProvider, capabilities: ['runtime.python'] },
 ],
 policy: {
 allowedTools: ['cloudflare.resource.read', 'search.code.run', 'sandbox.python'],
 resources: [
 { kind: 'cloudflare.d1', id: 'analytics', actions: ['read'] },
 { kind: 'dynamic_worker.execution', actions: ['execute'] },
 { kind: 'runtime.javascript', actions: ['execute'] },
 { kind: 'external.search', id: 'perplexity', actions: ['query'] },
 { kind: 'http.egress', id: 'api.example.com', actions: ['fetch'] },
 { kind: 'workspace.path', scope: '/runs', actions: ['write'] },
 { kind: 'sandbox.provider', id: 'sandbank-cloud', actions: ['execute'] },
 { kind: 'sandbox.provider', id: 'e2b', actions: ['execute'] },
 { kind: 'runtime.python', actions: ['execute'] },
 ],
 requireApproval: [
 { kind: 'cloudflare.d1', action: 'write' },
 ],
 },
 },
})

快速开始

# 安装推荐 provider
pnpm add @sandbank.dev/core @sandbank.dev/cloud
# 配置 Provider
export SANDBANK_API_TOKEN=your-key
# 或使用 x402 按次付费
export WALLET_PRIVATE_KEY=0x...

import { createProvider } from '@sandbank.dev/core'
import { SandbankCloudAdapter } from '@sandbank.dev/cloud'
const provider = createProvider(
 new SandbankCloudAdapter({ apiToken: process.env.SANDBANK_API_TOKEN })
)
// 创建沙箱
const sandbox = await provider.create({
 image: 'node:22',
 resources: { cpu: 2, memory: 2048 },
 autoDestroyMinutes: 30,
})
// 执行命令
const { stdout } = await sandbox.exec('node --version')
// 文件操作
await sandbox.writeFile('/app/index.js', 'console.log("hi")')
await sandbox.exec('node /app/index.js')
// 清理
await provider.destroy(sandbox.id)

开发

git clone https://github.com/chekusu/sandbank.git
cd sandbank
pnpm install
# 运行全部单元测试
pnpm test
# 运行跨 Provider 一致性测试
pnpm test:conformance
# 类型检查
pnpm typecheck

DB-native Harness API

DB9_DATABASE_ID=... DB9_TOKEN=... DEEPSEEK_API_KEY=... \
 vas dev sandbank-harness pnpm --filter ./packages/sandbank exec tsx src/cli/index.ts harness-api --host 0.0.0.0 --port 8789

pnpm --filter ./packages/sandbank exec tsx src/cli/index.ts harness-benchmark \
 --base-url https://your-sandbank-worker.example \
 --question "@agent run a Sandbank harness health check" \
 --json

SANDBANK_HARNESS_BASE_URL=https://your-sandbank-worker.example pnpm bench:harness -- --json

运行集成测试

# Sandbank Cloud(推荐默认 provider)
SANDBANK_API_TOKEN=... pnpm test
# Daytona
DAYTONA_API_KEY=... pnpm test
# Fly.io
FLY_API_TOKEN=... FLY_APP_NAME=... pnpm test
# Cloudflare
E2E_WORKER_URL=... pnpm test
# db9
DB9_TOKEN=... pnpm --filter @sandbank.dev/db9 test:e2e

测试覆盖率

pnpm --filter @sandbank.dev/db9 test -- --coverage

设计原则

许可证