沙箱 API 参考：Python 与 TypeScript SDK

SDK 是沙箱 REST API 之上的一层薄封装。它替你省掉三件事：手工拼请求、平台繁忙时重试、代码抛异常后忘记删除沙箱。本页内容对应两个包的 0.2.0 版本。

如果你从没创建过沙箱，先看 5 分钟连接指南 拿到 token。沙箱是什么、里面有什么，见 沙箱。

安装与配置

pip install eqvps          # Python 3.8+
npm i @eqvps/sdk           # Node.js 18+, Deno, Bun
export EQVPS_API_KEY=...   # your EQVPS account token

两种语言写的同一个程序：创建沙箱、运行代码、删除沙箱。

from eqvps import Sandbox

with Sandbox.create(tariff="small") as sb:
    r = sb.run("print(2 + 2)")
    print(r.exit_code, r.stdout)   # 0 4

import { Sandbox } from "@eqvps/sdk";

await Sandbox.with({ tariff: "small" }, async (sb) => {
  const r = await sb.run("print(2 + 2)");
  console.log(r.exit_code, r.stdout); // 0 4
});

创建与查找沙箱

Sandbox.create(...) 启动一个沙箱，通常约一秒。Python 使用关键字参数，TypeScript 使用一个选项对象。

Sandbox.connect(id) 连接到已有沙箱，通常是你昨天创建的持久沙箱。Sandbox.list() 返回账户下的全部沙箱，包括运行中和已暂停的。

属性：id（sb_ + 24 位十六进制字符）、mode、tariff、state（running、starting、paused、pausing、resuming、deleting、deleted）、env_keys / envKeys（只有名称，值永远不会返回）以及 info（原始对象）。refresh() 会重新加载这些属性。

kill() 删除沙箱并停止计费。对已经不存在的沙箱调用它不算错误。

运行代码

run(code, language="python", timeout=30) 通过 stdin 把代码交给 Python 3.12、Node.js 22 或 bash（"python"、"node"、"bash"）。exec(command, cwd=None, stdin=None, timeout=30) 执行 shell 命令：字符串经 bash -lc 执行，列表则作为 argv 直接执行、不经过 shell。

两者都返回 ExecResult：

一次同步调用 最长 55 秒。两个方法都接受只作用于本次调用的 env，它会覆盖创建时设置的值。

长任务：后台任务

传入 background=True（TypeScript：{ background: true }），立即得到一个 Task。它没有 55 秒限制，可以一直运行到沙箱生命周期结束。每个沙箱最多 8 个任务。

task = sb.exec("cd /root/app && python3 -m pytest -q", background=True)
result = task.wait(on_output=lambda out, err: print(out, end=""))
print(result.state, result.exit_code)   # done 0

const task = await sb.exec("cd /root/app && npm test", { background: true });
const result = await task.wait({ onOutput: (out) => process.stdout.write(out) });

如果 wait 自身超时，会抛出 SandboxTimeoutError，但任务仍在运行。运行中的任务还会阻止临时沙箱因空闲被删除。

文件与用量

upload(path, content, mode=None) 把文件写到绝对路径并返回其大小。download(path) 返回字节，download_text(path) / downloadText(path) 返回字符串。单次传输上限 5 MB。

usage() 返回运行秒数、已用 CPU 秒数、出站字节、每小时价格、billed_usd 和 estimated_total_usd。tariffs() 是一个无需密钥的普通函数，返回当前价格和限制。计费规则见 沙箱限制与计费。

错误

所有 API 错误都是 EqvpsError 的子类，带有 status（HTTP 状态）、code（稳定的字符串）和 body。服务器返回时会填充 retry_after / retryAfter。

大多数 429 来自两个限制：一个账户 同时最多执行 2 条命令，最多持有 20 个沙箱。服务器告知等待时间时 SDK 会自动重试，三次之后抛出异常。

什么时候不需要 SDK

任何有 HTTP 客户端的语言都可以直接调用 API，接口定义在 https://eqvps.com/openapi.json 的 OpenAPI 文件里。在 Claude、Cursor 或其他 MCP 客户端里运行的代理完全不需要写代码：MCP 服务器 提供同样的沙箱工具。如果只是想看看效果，沙箱页面 列出了套餐以及新账户的 $1 试用。