快速开始
获取访问凭证、安装 tensor-box SDK（TypeScript / Python / Go / CLI），并在 30 行代码内跑通第一个沙箱。
本页带你从零到一：拿到访问凭证 → 安装 SDK → 创建沙箱、执行命令、读写文件、回收。Tensor Box 提供 TypeScript / Python / Go 三语言 SDK 以及一个 tensor-box CLI，四套接口共用同一套控制面 HTTP / WebSocket API。
1. 获取 domain 与 API Key
Tensor Box 已上线于 app.tos.run，访问凭证在控制台签发：
- 登录 app.tos.run 控制台，进入「智能体沙箱」。
- 打开 「密钥凭证」 标签页，新建一个 API Key 并复制保存。
- 记下你要连接的控制面地址，作为 SDK 的
domain（公有云为https://app.tos.run；私有化部署以你实际的部署域名为准）。
公有云直接用 https://app.tos.run 即可；若为私有化 / 企业部署，domain 与 apiKey 均来自你自己的 Tensor OS 部署控制台「密钥凭证」。如尚未开通沙箱能力，请联系我们。
2. 安装 SDK
按你的语言选择安装方式（包名统一为 tensor-box，无 org scope）：
npm install tensor-box
# 或 pnpm add tensor-box / yarn add tensor-boxnpm 包名 tensor-box，导入 import { Sandbox } from 'tensor-box'。
pip install tensor-boxPyPI 包名 tensor-box，导入模块名为 tensor_box（下划线）：from tensor_box import Sandbox。
go get github.com/NexusGPU/tensor-box/sdk/go模块路径 github.com/NexusGPU/tensor-box/sdk/go，包名为 tensorbox。需 Go 1.24+。
npm install -g tensor-box-cli
# 或免安装直接运行
npx tensor-box-cli --help安装后的可执行文件名为 tensor-box。
SDK 已发布到公共 npm / PyPI / Go module。若你的环境无法访问公共源，请向我们获取私有源地址或离线分发包。
3. 配置凭证
SDK 通过 apiKey + domain 两个参数定位你的部署。凭证按以下优先级解析（从高到低）：
- 调用时显式传入的
apiKey/domain - 环境变量
TENSOR_BOX_API_KEY/TENSOR_BOX_DOMAIN - 旧版兼容回退
E2B_API_KEY/E2B_DOMAIN
推荐把凭证放进环境变量：
export TENSOR_BOX_API_KEY="你的-api-key" # 旧代码用 E2B_API_KEY 也仍可识别
export TENSOR_BOX_DOMAIN="https://app.tos.run"从 E2B 迁移时，已有的 E2B_API_KEY / E2B_DOMAIN 可继续使用，无需改动；但 SDK 会优先读取 TENSOR_BOX_*。WebSocket（PTY 终端、文件监听、后台进程流）通过 X-API-Key 升级请求头携带凭证，不再放在 URL query 里。
4. Hello-Sandbox
下面这段代码完整演示了一个沙箱的生命周期：创建 → 执行命令 → 写文件 → 读文件 → 回收。凭证默认取自 TENSOR_BOX_API_KEY / TENSOR_BOX_DOMAIN 环境变量。
import { Sandbox } from 'tensor-box';
async function main() {
// 1. 创建沙箱（apiKey/domain 取自 TENSOR_BOX_* 环境变量）
const sandbox = await Sandbox.create('default', {
timeoutMs: 60_000, // 60s 无活动后回收
metadata: { project: 'hello-sandbox' },
});
console.log('sandbox id:', sandbox.sandboxId);
// 2. 执行一条命令，拿到 stdout / exitCode
const res = await sandbox.commands.run('echo "Hello from microVM" && uname -a');
console.log(res.stdout);
console.log('exit code:', res.exitCode);
// 3. 写文件
await sandbox.files.write('/home/user/greeting.txt', 'Hello, Tensor Box!');
// 4. 读回文件
const text = await sandbox.files.read('/home/user/greeting.txt');
console.log('file says:', text);
// 5. 回收沙箱
await sandbox.kill();
}
main().catch(console.error);from tensor_box import Sandbox
def main():
# 1. 创建沙箱（凭证取自 TENSOR_BOX_* 环境变量）
sandbox = Sandbox.create("default", timeout_ms=60_000, metadata={"project": "hello-sandbox"})
print("sandbox id:", sandbox.sandbox_id)
# 2. 执行一条命令
res = sandbox.commands.run('echo "Hello from microVM" && uname -a')
print(res.stdout)
print("exit code:", res.exit_code)
# 3. 写文件
sandbox.files.write("/home/user/greeting.txt", "Hello, Tensor Box!")
# 4. 读回文件
text = sandbox.files.read("/home/user/greeting.txt")
print("file says:", text)
# 5. 回收沙箱
sandbox.kill()
if __name__ == "__main__":
main()package main
import (
"context"
"fmt"
"log"
"time"
tensorbox "github.com/NexusGPU/tensor-box/sdk/go"
)
func main() {
ctx := context.Background()
// 1. 创建沙箱（凭证取自 TENSOR_BOX_* 环境变量）
sandbox, err := tensorbox.Create(ctx, "default", &tensorbox.CreateOptions{
Timeout: 60 * time.Second, // 60s 无活动后回收
Metadata: map[string]string{"project": "hello-sandbox"},
})
if err != nil {
log.Fatal(err)
}
defer sandbox.Kill(ctx)
fmt.Println("sandbox id:", sandbox.SandboxID)
// 2. 执行一条命令
res, err := sandbox.Commands.Run(ctx, `echo "Hello from microVM" && uname -a`, nil)
if err != nil {
log.Fatal(err)
}
fmt.Println(res.Stdout)
fmt.Println("exit code:", res.ExitCode)
// 3. 写文件
if _, err := sandbox.Files.WriteString(ctx, "/home/user/greeting.txt", "Hello, Tensor Box!", nil); err != nil {
log.Fatal(err)
}
// 4. 读回文件
text, _ := sandbox.Files.Read(ctx, "/home/user/greeting.txt", nil)
fmt.Println("file says:", text)
}# 一次性保存凭证（写入 ~/.tensor-box/config.json，chmod 600）
tensor-box auth login --api-key "$TENSOR_BOX_API_KEY" --domain https://app.tos.run
tensor-box auth status
# 创建沙箱并拿到 ID
sbx=$(tensor-box sandbox create default --json | jq -r .sandboxId)
# 执行命令（实时流式输出 stdout / stderr）
tensor-box sandbox exec "$sbx" 'echo "Hello from microVM" && uname -a'
# 回收
tensor-box sandbox kill "$sbx"运行后你会看到命令输出、内核信息以及写回的文件内容。Sandbox.create 的第一个参数是模板（这里用内置的 default），第二个参数是创建选项。
Go SDK 的 Timeout 是 time.Duration（如 60 * time.Second），其余语言的 timeoutMs / timeout_ms 是毫秒整数——底层控制面统一以秒为单位，SDK 自动换算。