5 分钟上手沙箱 Python SDK：从 pip install eqvps 到第一次运行

本教程带你从零开始，在 Python 里跑起一个沙箱。你会启动一台隔离的 Firecracker 微虚拟机（microVM），在里面运行代码、安装软件包、把文件传进传出，再在后台跑一个耗时任务。每一步都只是几行可直接粘贴的代码。

你需要 Python 3.8 或更高版本，以及一个 EQVPS 账户。SDK 没有任何依赖。

1. 获取令牌

沙箱从账户余额中扣费，所以 SDK 需要账户令牌。连接账户页面介绍了三种获取方式：控制面板、API 或 MCP 服务器。然后把它写入环境变量：

export EQVPS_API_KEY="your-token"

还没有余额？没关系。新账户第一次在余额不足时创建沙箱，会获得 1 美元沙箱额度，有效期 14 天。

2. 安装 SDK

pip install eqvps

3. 启动沙箱并运行代码

把下面的内容保存为 hello.py 并运行：

from eqvps import Sandbox

with Sandbox.create(tariff="small") as sb:
    print(sb.id)
    r = sb.run("import platform; print(platform.python_version())")
    print(r.exit_code, r.stdout)

你会看到沙箱 id（sb_ 加 24 个字符），然后是 0 3.12.x。沙箱大约 1 秒就启动了，执行完代码，在 with 代码块结束时被删除。

关于返回结果，有几点值得了解：

• 退出码为 0 且命令没有超时，r.ok 才为 true；
• 非零退出码不是异常，需要自己检查 r.ok；
• stdout 和 stderr 各自上限 1 MiB，输出被截断时 r.truncated 会告诉你。

4. 安装软件包并运行 shell 命令

在沙箱里，你是一个小型 Linux 系统的 root，系统自带 Python、Node.js、git 和 curl。exec 可以运行任何 shell 命令：

from eqvps import Sandbox

with Sandbox.create(tariff="small") as sb:
    sb.exec("pip install --quiet requests", timeout=55)
    r = sb.run("import requests; print(requests.get('https://example.com').status_code)")
    print(r.stdout)   # 200

默认超时是 30 秒，一次同步调用最多 55 秒。大型安装应放到后台任务里（第 6 步）。

5. 把文件传进传出

from eqvps import Sandbox

with Sandbox.create() as sb:
    sb.upload("/root/data.csv", "a,b\n1,2\n3,4\n")
    sb.run("""
import csv
rows = list(csv.DictReader(open('/root/data.csv')))
open('/root/sum.txt', 'w').write(str(sum(int(r['b']) for r in rows)))
""")
    print(sb.download_text("/root/sum.txt"))   # 6

路径必须是绝对路径。单次传输上限 5 MB；download 返回字节，download_text 返回字符串。

6. 在后台运行长任务

传入 background=True，你会立刻拿到一个任务对象，不必等待。它没有 55 秒的限制：

from eqvps import Sandbox

with Sandbox.create(tariff="standard") as sb:
    task = sb.exec("for i in 1 2 3 4 5; do echo step $i; sleep 20; done", background=True)
    result = task.wait(on_output=lambda out, err: print(out, end=""))
    print(result.state, result.exit_code)   # done 0

task.wait() 每 2 秒轮询一次，新输出一到就打印出来。你也可以自己调用 task.logs()，或用 task.kill() 停止任务。任务运行期间，沙箱不会因空闲而被删除。

花了多少钱

上面每个 with 代码块只存在了几秒，按最低 60 秒计费。在 small 上每个代码块是 0.00055 美元，五个示例加起来大约三分之一美分。各套餐价格、持久模式和消费上限见沙箱限制与计费。

出错时怎么办

API 错误是可以捕获的异常：

from eqvps import Sandbox, InsufficientBalanceError, RateLimitError

try:
    with Sandbox.create() as sb:
        print(sb.run("print(1)").stdout)
except InsufficientBalanceError:
    print("Top up the balance")
except RateLimitError as e:
    print("Too many at once, retry in", e.retry_after)

当服务器告知需要等待多久时，SDK 已经会自动重试 429 和 503 响应，最多 3 次。全部 11 种错误类型列在 SDK 参考中。

下一步

• 同样的步骤用 JavaScript 实现：5 分钟上手沙箱 TypeScript SDK。
• 让 AI 模型写代码并在这里运行：在沙箱中完成第一个智能体任务。
• 套餐、试用额度以及沙箱里有什么：沙箱页面。