TensorFusion Docs

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)。

鉴权

  • SDKSandbox.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(createSnapshotcreate_snapshottimeoutMstimeout_ms),模块名 tensor_box;Go 用 PascalCase(Sandbox.createtensorbox.Createread({format}) 拆为 Read/ReadBytes/ReadStreamrun({background}) 拆为 Run/RunBackground、静态按 ID 方法后缀 ByIDTimeouttime.Duration 而非毫秒)。各语言完整签名见对应章节的 Tabs 与 SDK README。

Sandbox(生命周期)

方法返回说明
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.sandboxIdsandbox.templateIdsandbox.sandboxDomainsandbox.commandssandbox.filessandbox.pty

commands(命令执行)

方法返回说明
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 写入

CommandStartOptsbackground / cwd / envs / timeoutMs / user / onStdout / onStderr / requestTimeoutMsCommandHandlepid / wait() / kill() / disconnect()

files(文件系统)

方法返回说明
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

EntryInfoname / path / type'file' | 'dir')/ size / mode / permissions / owner / group / modifiedTime / symlinkTarget

pty(交互终端)

方法返回说明
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 写入输入

PtyHandlepid / 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, &notFound):
	fmt.Println("沙箱不存在")
case errors.As(err, &authErr):
	fmt.Println("API Key 无效")
}
// 所有类型都 unwrap 到 *SandboxError,可用 tensorbox.AsSandboxError(err) 取 StatusCode。

控制面 REST 端点

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列出快照

命令(guest-agent 代理)

方法路径说明
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进程输出流

文件系统(guest-agent 代理)

方法路径说明
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/terminalPTY 终端(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 环境或需要底层对接时参考。

目录