TensorFusion Docs

快照与模板

用暂停 / 恢复保存会话状态，创建快照，构建自定义模板（编程式与 CLI 两种方式），并把运行中的沙箱固化成模板。

Tensor Box 提供两类"持久化"能力：快照用于保存某个沙箱的运行时状态，模板用于把一套环境固化成可复用的镜像，供后续创建沙箱时秒级拉起。

快照：保存运行时状态

暂停即快照

最常用的方式是暂停 / 恢复——暂停会把沙箱的内存与磁盘状态一起快照化，之后可在任意计算节点上恢复，秒级回到原状态：

await sandbox.pause();        // 状态保存，释放计算资源
// ... 稍后
await sandbox.resume();       // 在任意节点恢复，会话无缝继续
sandbox.pause()        # 状态保存，释放计算资源
# ... 稍后
sandbox.resume()       # 在任意节点恢复，会话无缝继续
sandbox.Pause(ctx)              // 状态保存，释放计算资源
// ... 稍后
sandbox.Resume(ctx, 0)         // 在任意节点恢复（0 = 不重设超时）

显式创建 / 列出快照

也可以在不暂停的情况下显式打一个快照：

import { Snapshot } from 'tensor-box';

// 显式创建快照（沙箱保持运行）
const snap = await sandbox.createSnapshot('before-risky-step');
// -> { snapshotId, sandboxId, name }

// 列出快照
const all = await Snapshot.list({ domain, apiKey });
const ofOne = await Snapshot.list({ domain, apiKey, sandboxId: 'sbx_abc123' });
from tensor_box import Snapshot

# 显式创建快照（沙箱保持运行）
snap = Snapshot.create(sandbox.sandbox_id, name="before-risky-step")
# 或实例方法：sandbox.create_snapshot("before-risky-step")

# 列出快照
all_snaps = Snapshot.list()
of_one = Snapshot.list(sandbox_id="sbx_abc123")
// 显式创建快照（沙箱保持运行）
snap, _ := sandbox.CreateSnapshot(ctx, "before-risky-step")
// -> SnapshotInfo{SnapshotID, SandboxID, Name}

// 列出快照
all, _ := tensorbox.ListSnapshots(ctx, nil)
ofOne, _ := tensorbox.ListSnapshots(ctx, &tensorbox.SnapshotListOptions{SandboxID: "sbx_abc123"})

快照与暂停状态保存在共享 / 分布式存储中，因此一个在 A 节点暂停的沙箱可以在 B 节点恢复——这是"任意节点恢复"的基础。具体存储后端由你的 Tensor OS 部署配置决定。

模板：可复用的环境

模板是创建沙箱时的起点镜像。内置 default 模板基于 Ubuntu 24.04；你也可以构建自定义模板，预装工具链、依赖、数据，让后续沙箱开箱即用。

列出基础镜像 / 模板

import { Template } from 'tensor-box';

const bases = await Template.listBaseImages({ domain, apiKey });
// [{ dockerImage: 'ubuntu:24.04', osVersion: '24.04', codename: 'noble', status: 'ready', ... }]

const templates = await Template.list({ domain, apiKey });
const one = await Template.get('tmpl_abc', { domain, apiKey });
from tensor_box import Template

bases = Template.list_base_images()
templates = Template.list()
one = Template.get("tmpl_abc")
bases, _ := tensorbox.ListBaseImages(ctx, nil)
templates, _ := tensorbox.ListTemplates(ctx, nil)
one, _ := tensorbox.GetTemplate(ctx, "tmpl_abc", nil)
tensor-box template base-images   # 可用基础镜像（别名 bases）
tensor-box template list          # 已有模板（别名 ls）
tensor-box template get tmpl_abc  # 查询单个模板（别名 info）

编程式构建自定义模板

模板可以从已有模板派生（fromTemplate）、从基础镜像（fromImage）或 Dockerfile（dockerfile）创建。构建分两步：先 create 拿到 templateID + buildID，再 startBuild 提交构建配置，最后轮询状态 / 日志。

关于 Dockerfile / fromImage 构建路径：当前 dockerfile 与 fromImage（从零镜像构建）构建链路正在加固中——一个 JuiceFS qcow2 存储修复正在推进（对应内部工单 S1.3）。在该修复落地前，经过验证、当前可用的路径是从已有模板派生 + 构建步骤（fromTemplate + steps）。下面的 fromTemplate 示例可直接运行；fromImage / dockerfile 示例写法正确，但请在 S1.3 落地后再用于生产。

import { Template } from 'tensor-box';

// 1. 创建模板占位
const { templateID, buildID } = await Template.create(
  { name: 'agent-runtime', cpuCount: 4, memoryMB: 4096 },
  { domain, apiKey },
);

// 2. 启动构建 —— 当前验证可用的路径：从已有模板派生 + 构建步骤
await Template.startBuild(templateID, buildID, {
  fromTemplate: 'default',            // ✅ 已验证：基于已就绪的模板派生
  steps: [
    { name: 'deps', command: 'apt-get update && apt-get install -y ffmpeg python3-pip' },
    { name: 'pip', command: 'pip install numpy pandas' },
  ],
  startCmd: 'python3 /app/server.py',          // 可选：沙箱启动命令
  readyCmd: 'curl -sf localhost:8000/health',  // 可选：就绪探测命令
}, { domain, apiKey });

// —— 以下两种来源在 S1.3 (JuiceFS qcow2 修复) 落地后启用 ——
// a) 从基础镜像： { fromImage: 'ubuntu:24.04', steps: [...] }
// b) 从 Dockerfile： { dockerfile: 'FROM ubuntu:24.04\nRUN apt-get update ...' }

// 3. 轮询构建状态 / 日志
const status = await Template.getBuildStatus(templateID, buildID, { domain, apiKey });
const logs = await Template.getBuildLogs(templateID, buildID, { domain, apiKey });
from tensor_box import Template

# 1. 创建模板占位
created = Template.create(name="agent-runtime", cpu_count=4, memory_mb=4096)
template_id, build_id = created["templateID"], created["buildID"]

# 2. 启动构建 —— 当前验证可用的路径：fromTemplate + steps
Template.start_build(
    template_id, build_id,
    from_template="default",            # ✅ 已验证：基于已就绪的模板派生
    steps=[
        {"name": "deps", "command": "apt-get update && apt-get install -y ffmpeg python3-pip"},
        {"name": "pip", "command": "pip install numpy pandas"},
    ],
    start_cmd="python3 /app/server.py",          # 可选
    ready_cmd="curl -sf localhost:8000/health",  # 可选
)

# —— 以下两种来源在 S1.3 落地后启用 ——
# a) from_image="ubuntu:24.04", steps=[...]
# b) dockerfile="FROM ubuntu:24.04\nRUN apt-get update ..."

# 3. 轮询构建状态 / 日志
status = Template.get_build_status(template_id, build_id)
logs = Template.get_build_logs(template_id, build_id)
// 1. 创建模板占位
created, _ := tensorbox.CreateTemplate(ctx,
	&tensorbox.TemplateCreateOptions{Name: "agent-runtime", CPUCount: 4, MemoryMB: 4096}, nil)

// 2. 启动构建 —— 当前验证可用的路径：FromTemplate + Steps
err := tensorbox.StartBuild(ctx, created.TemplateID, created.BuildID,
	&tensorbox.TemplateBuildOptions{
		FromTemplate: "default", // ✅ 已验证：基于已就绪的模板派生
		Steps: []tensorbox.TemplateBuildStep{
			{Name: "deps", Command: "apt-get update && apt-get install -y ffmpeg python3-pip"},
			{Name: "pip", Command: "pip install numpy pandas"},
		},
		StartCmd: "python3 /app/server.py",
		ReadyCmd: "curl -sf localhost:8000/health",
	}, nil)

// —— S1.3 落地后启用 FromImage: "ubuntu:24.04" 或 Dockerfile: "FROM ..." ——

// 3. 轮询构建状态 / 日志
status, _ := tensorbox.GetBuildStatus(ctx, created.TemplateID, created.BuildID, nil)
logs, _ := tensorbox.GetBuildLogs(ctx, created.TemplateID, created.BuildID, nil)

CLI 把"创建 + 启动构建 + 轮询"封装成 template init / template build 两步，配置写在 e2b.toml 里：

# 1. 脚手架生成 e2b.toml（不联网）
tensor-box template init \
  --name agent-runtime \
  --from-image ubuntu:24.04 \
  --cpu 4 --memory 4096

# 2. 注册并构建：流式打印构建日志，等待 ready
tensor-box template build --config e2b.toml

template build 读取 e2b.toml，调用 Template.create 分配 template_id + build_id（写回文件），再以 from_image / dockerfile / steps / start_cmd / ready_cmd 字段调用 Template.startBuild，并轮询直到 ready（除非 --no-wait）。

e2b.toml（CLI 模板配置）

tensor-box template init 生成的是 e2b.toml 兼容格式。把 from_image 换成 from_template = "default" 即可走当前已验证的派生路径：

# TensorBox 模板配置（兼容 e2b.toml）
name = "agent-runtime"
from_template = "default"   # ✅ 已验证路径；from_image 待 S1.3 落地后使用
cpu_count = 4
memory_mb = 4096

[[steps]]
name = "deps"
command = "apt-get update && apt-get install -y ffmpeg python3-pip"

[[steps]]
name = "pip"
command = "pip install numpy pandas"

构建完成后，用模板 ID 创建沙箱即可获得预装好的环境：

const sandbox = await Sandbox.create(templateID, { domain });
sandbox = Sandbox.create(template_id, domain=domain)
sandbox, _ := tensorbox.Create(ctx, created.TemplateID, nil)
tensor-box sandbox create agent-runtime --json

把运行中的沙箱固化成模板

这是最便捷的"环境复用"方式：在一个正在运行的沙箱里把环境配好，再一键固化成模板。源沙箱在整个过程中保持运行。它走的正是已验证的快照派生路径，不依赖 S1.3。

const sbx = await Sandbox.create('default', { domain });

// 在沙箱里安装好需要的东西
await sbx.commands.run('apt-get update && apt-get install -y ffmpeg');

// 固化成模板（SDK 默认会轮询直到构建完成）
const tpl = await sbx.commitAsTemplate('ubuntu-with-ffmpeg', {
  cpuCount: 2,
  memoryMB: 2048,
  diskGB: 40,
});

// 之后创建的沙箱都预装好了 ffmpeg
const sbx2 = await Sandbox.create(tpl.templateID, { domain });
sbx = Sandbox.create("default", domain=domain)
sbx.commands.run("apt-get update && apt-get install -y ffmpeg")

# 固化成模板（默认轮询直到构建完成）
tpl = sbx.commit_as_template("ubuntu-with-ffmpeg", cpu_count=2, memory_mb=2048, disk_gb=40)

sbx2 = Sandbox.create(tpl.template_id, domain=domain)
sbx, _ := tensorbox.Create(ctx, "default", nil)
sbx.Commands.Run(ctx, "apt-get update && apt-get install -y ffmpeg", nil)

// 固化成模板（默认轮询直到构建完成）
tpl, _ := sbx.CommitAsTemplate(ctx, "ubuntu-with-ffmpeg", &tensorbox.CommitOptions{
	CPUCount: 2, MemoryMB: 2048, DiskGB: 40,
})

sbx2, _ := tensorbox.Create(ctx, tpl.TemplateID, nil)

固化的构建在服务端后台进行（快照 + 镜像生成，通常 30 秒到数分钟）。SDK 默认会轮询到构建就绪（buildStatus: "ready"）才返回；传 wait: false（Python wait=False / Go CommitOptions.Wait）可在请求被接受后立即返回，自行通过 getBuildStatus 跟踪。

持久化 vs 临时盘

  • 临时盘 — 沙箱运行期间的磁盘是临时的；销毁沙箱后随之释放。适合一次性任务。
  • 快照 / 暂停 — 通过暂停或显式快照把状态保存到共享存储，可跨节点恢复，适合需要"挂起再继续"的长会话。
  • 模板 — 把整套环境固化成可复用镜像，供后续大量沙箱共享同一基线，是跨会话复用的正确方式。

方法一览

方法（TS / Python / Go / CLI）说明
pause·resume / pause·resume / Pause·Resume / —暂停（内存 + 磁盘快照）/ 恢复
createSnapshot / Snapshot.create·create_snapshot / CreateSnapshot / —显式创建快照
Snapshot.list / Snapshot.list / ListSnapshots / —列出快照（可按沙箱 ID 过滤）
commitAsTemplate / commit_as_template / CommitAsTemplate / —把运行中的沙箱固化成模板
Template.listBaseImages / Template.list_base_images / ListBaseImages / template base-images列出可用基础镜像
Template.list·get / Template.list·get / ListTemplates·GetTemplate / template list·get列出 / 查询模板
Template.create / Template.create / CreateTemplate / template init创建模板占位 / 脚手架配置
Template.startBuild / Template.start_build / StartBuild / template build启动构建（fromTemplate✅ / steps / fromImage·dockerfile 待 S1.3）
Template.getBuildStatus·getBuildLogs / get_build_status·get_build_logs / GetBuildStatus·GetBuildLogs / template build 自动轮询查询构建状态 / 日志
Template.delete / Template.delete / DeleteTemplate / template delete删除模板

沙箱生命周期

创建、连接、列举沙箱，暂停与恢复，设置超时与保活，以及超时回收策略。

控制台管理与运行观测

在控制台管理每个智能体的沙箱运行时（模板 / CLI / 模型 / 环境变量），并查看会话的运行状态与完整执行轨迹。

目录

快照：保存运行时状态暂停即快照显式创建 / 列出快照模板：可复用的环境列出基础镜像 / 模板编程式构建自定义模板e2b.toml（CLI 模板配置）把运行中的沙箱固化成模板持久化 vs 临时盘方法一览