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 模型寫程式碼並在這裡執行：在沙箱中完成第一個代理任務。
• 方案、試用額度以及沙箱裡有什麼：沙箱頁面。