API 参考
Tensor Box 多语言 SDK(TypeScript / Python / Go / CLI)的方法速查、错误类型,以及控制面 REST 端点表。
本页汇总 tensor-box SDK(TypeScript / Python / Go)的方法表面、错误类型,以及底层控制面的 REST 端点。所有方法均与代码实现一致。SDK 包名统一为 tensor-box(无 org scope):npm tensor-box、PyPI tensor-box(导入 tensor_box)、Go module github.com/NexusGPU/tensor-box/sdk/go(包名 tensorbox)。
- SDK:
Sandbox.create / connect / list 等通过 apiKey + domain 鉴权。凭证解析优先级:显式参数 → TENSOR_BOX_API_KEY / TENSOR_BOX_DOMAIN → 旧版回退 E2B_API_KEY / E2B_DOMAIN。
- 控制面 REST:所有受保护端点要求请求头
X-API-Key: <你的 API Key>。
- WebSocket(PTY 终端、文件监听、后台进程流):凭证通过
X-API-Key 升级请求头携带,不再放在 URL query string 里。
import { Sandbox } from 'tensor-box';
const sandbox = await Sandbox.create('default', {
apiKey: process.env.TENSOR_BOX_API_KEY, // 或省略,SDK 自动读 TENSOR_BOX_API_KEY / E2B_API_KEY
domain: 'https://app.tos.run', // 或省略,自动读 TENSOR_BOX_DOMAIN / E2B_DOMAIN
});
from tensor_box import Sandbox
sandbox = Sandbox.create(
"default",
api_key="...", # 或省略,自动读 TENSOR_BOX_API_KEY / E2B_API_KEY
domain="https://app.tos.run", # 或省略,自动读 TENSOR_BOX_DOMAIN / E2B_DOMAIN
)
sandbox, err := tensorbox.Create(ctx, "default", &tensorbox.CreateOptions{
Options: tensorbox.Options{
APIKey: "...", // 或留空,自动读 TENSOR_BOX_API_KEY / E2B_API_KEY
Domain: "https://app.tos.run", // 或留空,自动读 TENSOR_BOX_DOMAIN / E2B_DOMAIN
},
})
# 凭证可来自 flag / ~/.tensor-box/config.json / TENSOR_BOX_* / E2B_*(旧版回退)
tensor-box auth login --api-key tb_xxx --domain https://app.tos.run
tensor-box sandbox create default --api-key tb_xxx --domain https://app.tos.run
下列方法表以 TypeScript 命名为准。跨语言命名约定:Python 用 snake_case(createSnapshot → create_snapshot、timeoutMs → timeout_ms),模块名 tensor_box;Go 用 PascalCase(Sandbox.create → tensorbox.Create、read({format}) 拆为 Read/ReadBytes/ReadStream、run({background}) 拆为 Run/RunBackground、静态按 ID 方法后缀 ByID,Timeout 为 time.Duration 而非毫秒)。各语言完整签名见对应章节的 Tabs 与 SDK README。
| 方法 | 返回 | 说明 |
|---|
Sandbox.create(template?, opts?) | Sandbox | 创建沙箱。opts: timeoutMs / envs / metadata / apiKey / domain / requestTimeoutMs / lifecycle |
Sandbox.connect(id, opts?) | Sandbox | 连接已有沙箱(暂停的自动恢复) |
Sandbox.list(opts?) | SandboxInfo[] | 列举沙箱,过滤:state[] / metadata(TS 在 query;Python 直接传 state= / metadata=;Go 在 ListOptions) |
Sandbox.kill(id, opts?) | boolean | 静态:按 ID 销毁 |
Sandbox.pause(id, opts?) | boolean | 静态:按 ID 暂停 |
Sandbox.setTimeout(id, ms, opts?) | void | 静态:按 ID 设置超时 |
Sandbox.getInfo(id, opts?) | SandboxInfo | 静态:按 ID 取信息 |
Sandbox.getMetrics(id, opts?) | SandboxMetrics[] | 静态:按 ID 取指标 |
Sandbox.createSnapshot(id, opts?) | SnapshotInfo | 静态:按 ID 创建快照 |
sandbox.kill() | boolean | 销毁当前沙箱 |
sandbox.pause() | boolean | 暂停 |
sandbox.resume(timeoutMs?) | void | 恢复 |
sandbox.setTimeout(ms) | void | 重设无活动超时 |
sandbox.keepAlive(ms) | void | 延长存活时间 |
sandbox.getInfo() | SandboxInfo | 取信息 |
sandbox.getMetrics() | SandboxMetrics[] | 取指标(CPU / 内存 / 磁盘) |
sandbox.getLogs() | SandboxLogEntry[] | 取日志 |
sandbox.isRunning() | boolean | 是否运行中 |
sandbox.disconnect() | void | 断开 SDK 但保持沙箱运行 |
sandbox.getHost(port) | string | 端口对外主机名(<id>-<port>.<domain>) |
sandbox.downloadUrl(path) | string | 下载 URL |
sandbox.uploadUrl(path?) | string | 上传 URL |
只读属性:sandbox.sandboxId、sandbox.templateId、sandbox.sandboxDomain、sandbox.commands、sandbox.files、sandbox.pty。
| 方法 | 返回 | 说明 |
|---|
commands.run(cmd, opts?) | CommandResult | 前台执行({ stdout, stderr, exitCode }) |
commands.run(cmd, { background: true, ... }) | CommandHandle | 后台执行 |
commands.list() | Array<{ processId, pid, cmd, status, exitCode }> | 列出进程 |
commands.connect(pid) | CommandHandle | 连接到运行中的进程 |
commands.kill(pid) | boolean | 按 PID 杀进程 |
commands.sendStdin(pid, data) | void | 向进程 stdin 写入 |
CommandStartOpts:background / cwd / envs / timeoutMs / user / onStdout / onStderr / requestTimeoutMs。
CommandHandle:pid / wait() / kill() / disconnect()。
| 方法 | 返回 | 说明 |
|---|
files.read(path, { format }) | string / Uint8Array / ReadableStream | 读文件,format: 'text'(默认)/ 'bytes' / 'stream' |
files.write(path, data, opts?) | EntryInfo | 写单个文件 |
files.write(entries[], opts?) | EntryInfo[] | 批量写 |
files.list(path, opts?) | EntryInfo[] | 列目录 |
files.makeDir(path, opts?) | boolean | 创建目录(含父目录) |
files.exists(path, opts?) | boolean | 是否存在 |
files.rename(old, new, opts?) | EntryInfo | 重命名 / 移动 |
files.remove(path, opts?) | void | 删除 |
files.getInfo(path, opts?) | EntryInfo | 取文件 / 目录信息 |
files.watchDir(path, onEvent, opts?) | { stop } | 监听变更(create / write / remove) |
EntryInfo:name / path / type('file' | 'dir')/ size / mode / permissions / owner / group / modifiedTime / symlinkTarget。
| 方法 | 返回 | 说明 |
|---|
pty.create(opts?) | PtyHandle | 创建 PTY 会话。opts: cols / rows / cmd / envs / cwd / onData / timeoutMs / user |
pty.kill(pid) | boolean | 按 PID 结束会话 |
pty.resize(pid, { cols, rows }) | void | 按 PID 调整尺寸 |
pty.sendInput(pid, data) | void | 按 PID 写入输入 |
PtyHandle:pid / sendInput(data) / resize({ cols, rows }) / kill() / isOpen。
| 方法 | 返回 | 说明 |
|---|
sandbox.createSnapshot(name?) | SnapshotInfo | 创建快照 |
Snapshot.list(opts?) | SnapshotInfo[] | 列出快照(可按 sandboxId 过滤) |
sandbox.commitAsTemplate(name?, opts?) | CommitSandboxResult | 把运行中的沙箱固化为模板。opts: cpuCount / memoryMB / diskGB / wait / maxWaitMs / pollIntervalMs |
Template.listBaseImages(opts?) | BaseImageInfo[] | 列出可用基础镜像 |
Template.list(opts?) | TemplateInfo[] | 列出模板 |
Template.get(id, opts?) | TemplateInfo | 查询模板 |
Template.create(tplOpts?, opts?) | { templateID, buildID } | 创建模板占位。tplOpts: name / cpuCount / memoryMB |
Template.startBuild(id, buildId, buildOpts?, opts?) | void | 启动构建。buildOpts: fromTemplate✅(当前已验证)/ steps / startCmd / readyCmd / fromImage·dockerfile(构建链路加固中,详见快照与模板) |
Template.getBuildStatus(id, buildId, opts?) | { status, logs } | 查询构建状态 |
Template.getBuildLogs(id, buildId, opts?) | BuildLogEntry[] | 查询构建日志 |
Template.delete(id, opts?) | void | 删除模板 |
SDK 在出错时抛出以下错误类型,均继承 / 归并自 SandboxError(携带 statusCode / status_code / StatusCode 与解析后的错误 body):
| 错误类型 | 含义 |
|---|
SandboxError | 基类,携带状态码与 body |
NotFoundError | 资源不存在(如沙箱 / 模板 ID 无效) |
AuthenticationError | 鉴权失败(API Key 缺失或无效) |
RateLimitError | 触发限流 |
TimeoutError | 请求或操作超时 |
InvalidArgumentError | 参数非法 |
import { Sandbox, NotFoundError, AuthenticationError } from 'tensor-box';
try {
const sbx = await Sandbox.connect('sbx_missing', { domain });
} catch (e) {
if (e instanceof NotFoundError) console.error('沙箱不存在');
else if (e instanceof AuthenticationError) console.error('API Key 无效');
else throw e;
}
from tensor_box import Sandbox, NotFoundError, AuthenticationError
try:
sbx = Sandbox.connect("sbx_missing", domain=domain)
except NotFoundError:
print("沙箱不存在")
except AuthenticationError:
print("API Key 无效")
import "errors"
_, err := tensorbox.Connect(ctx, "sbx_missing", nil)
var notFound *tensorbox.NotFoundError
var authErr *tensorbox.AuthenticationError
switch {
case errors.As(err, ¬Found):
fmt.Println("沙箱不存在")
case errors.As(err, &authErr):
fmt.Println("API Key 无效")
}
// 所有类型都 unwrap 到 *SandboxError,可用 tensorbox.AsSandboxError(err) 取 StatusCode。
SDK 底层调用的是一套 E2B 兼容的 REST API。日常开发优先用 TypeScript / Python / Go SDK 或 tensor-box CLI;若你的语言暂无 SDK 或需要底层对接,可直接参考下表。除 /health 外,所有端点都要求 X-API-Key 请求头(WebSocket 端点亦通过 X-API-Key 升级头鉴权)。Base URL 即你的 domain。
| 方法 | 路径 | 说明 |
|---|
POST | /sandboxes | 创建沙箱 |
GET | /sandboxes | 列举沙箱 |
GET | /sandboxes/:id | 取沙箱信息 |
DELETE | /sandboxes/:id | 销毁沙箱 |
POST | /sandboxes/:id/pause | 暂停 |
POST | /sandboxes/:id/resume | 恢复 |
POST | /sandboxes/:id/timeout | 设置超时 |
POST | /sandboxes/:id/connect | 连接 |
POST | /sandboxes/:id/refreshes | 保活 |
GET | /sandboxes/:id/metrics | 取指标 |
GET | /sandboxes/metrics | 批量取指标 |
GET | /sandboxes/:id/logs | 取日志 |
POST | /sandboxes/:id/snapshots | 创建快照 |
POST | /sandboxes/:id/commit | 固化为模板 |
GET | /snapshots | 列出快照 |
| 方法 | 路径 | 说明 |
|---|
POST | /sandboxes/:id/exec | 前台执行 |
POST | /sandboxes/:id/exec/async | 后台执行 |
POST | /sandboxes/:id/exec/stream | 流式执行 |
GET | /sandboxes/:id/proc | 列进程 |
GET | /sandboxes/:id/proc/:pid | 查进程 |
GET | /sandboxes/:id/proc/:pid/output | 取进程输出 |
POST | /sandboxes/:id/proc/:pid/kill | 杀进程 |
POST | /sandboxes/:id/proc/:pid/stdin | 写 stdin |
GET | /sandboxes/:id/process/:pid/stream | 进程输出流 |
| 方法 | 路径 | 说明 |
|---|
GET | /sandboxes/:id/files/read | 读文件 |
POST | /sandboxes/:id/files/write | 写文件(JSON) |
PUT | /sandboxes/:id/files | 上传文件 |
GET | /sandboxes/:id/files/download | 下载文件 |
GET | /sandboxes/:id/files/list | 列目录 |
DELETE | /sandboxes/:id/files | 删除 |
POST | /sandboxes/:id/files/mkdir | 创建目录 |
POST | /sandboxes/:id/files/rename | 重命名 |
GET | /sandboxes/:id/files/stat | 取文件信息 |
GET | /sandboxes/:id/terminal | PTY 终端(WebSocket) |
| 方法 | 路径 | 说明 |
|---|
GET | /templates | 列出模板 |
POST | /templates | 创建模板 |
GET | /templates/:id | 查询模板 |
DELETE | /templates/:id | 删除模板 |
POST | /templates/:id/builds/:buildId | 启动构建 |
GET | /templates/:id/builds/:buildId/status | 构建状态 |
GET | /templates/:id/builds/:buildId/logs | 构建日志 |
GET | /base-images | 可用基础镜像 |
| 方法 | 路径 | 说明 |
|---|
GET | /api-keys | 列出 API Key |
POST | /api-keys | 创建 API Key |
DELETE | /api-keys/:id | 删除 API Key |
GET | /teams | 列出团队 |
GET | /teams/:id/metrics | 团队指标 |
上表覆盖最常用的端点;控制面还提供节点管理、访问令牌、管理员等内部端点。日常开发优先使用 SDK,REST 端点仅在非 TypeScript 环境或需要底层对接时参考。