Tài liệu tham khảo API sandbox: SDK Python và TypeScript

SDK là một lớp mỏng trên REST API của sandbox. Nó giúp bạn khỏi ba việc: tự dựng yêu cầu, thử lại khi nền tảng bận và quên xóa sandbox khi mã ném ngoại lệ. Mọi thứ ở đây ứng với phiên bản 0.2.0 của cả hai gói.

Nếu bạn chưa từng tạo sandbox, hướng dẫn kết nối 5 phút sẽ cấp token cho bạn trước. Sandbox là gì và bên trong có gì được giải thích ở trang Sandbox.

Cài đặt và cấu hình

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

Cùng một chương trình bằng hai ngôn ngữ: tạo sandbox, chạy mã, xóa nó.

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
});

Tạo và tìm sandbox

Sandbox.create(...) khởi động một sandbox, thường mất khoảng một giây. Python nhận đối số có tên, TypeScript nhận một đối tượng tùy chọn.

Sandbox.connect(id) gắn vào một sandbox có sẵn, thường là sandbox lâu dài bạn tạo hôm qua. Sandbox.list() trả về mọi sandbox của tài khoản, đang chạy và đang tạm dừng.

Thuộc tính: id (sb_ + 24 ký tự hex), mode, tariff, state (running, starting, paused, pausing, resuming, deleting, deleted), env_keys / envKeys (chỉ tên, giá trị không bao giờ được trả về) và info (đối tượng thô). refresh() tải lại chúng.

kill() xóa sandbox và dừng tính phí. Gọi nó cho sandbox đã không còn tồn tại không bị coi là lỗi.

Chạy mã

run(code, language="python", timeout=30) gửi mã qua stdin tới Python 3.12, Node.js 22 hoặc bash ("python", "node", "bash"). exec(command, cwd=None, stdin=None, timeout=30) chạy lệnh shell: chuỗi đi qua bash -lc, danh sách được chạy như argv không qua shell.

Cả hai trả về ExecResult:

Một lời gọi đồng bộ chạy tối đa 55 giây. Cả hai phương thức cũng nhận env cho riêng lời gọi đó; nó ghi đè các giá trị đặt lúc tạo.

Việc dài: tác vụ nền

Truyền background=True (TypeScript: { background: true }) và bạn nhận ngay một Task. Nó không bị giới hạn 55 giây và có thể chạy tới khi sandbox hết thời gian sống. Tối đa 8 tác vụ mỗi sandbox.

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) });

Nếu wait chạm thời gian chờ của chính nó, nó ném SandboxTimeoutError, nhưng tác vụ vẫn chạy tiếp. Một tác vụ đang chạy cũng ngăn sandbox tạm thời bị xóa vì không hoạt động.

Tệp và mức sử dụng

upload(path, content, mode=None) ghi tệp vào đường dẫn tuyệt đối và trả về kích thước. download(path) trả về byte, download_text(path) / downloadText(path) trả về chuỗi. Mỗi lần truyền giới hạn 5 MB.

usage() trả về số giây đã chạy, số giây CPU đã dùng, byte đi ra, giá theo giờ, billed_usd và estimated_total_usd. tariffs() là hàm thường, không cần khóa, trả về giá và giới hạn hiện hành. Quy tắc tính phí ở trang Giới hạn và tính phí sandbox.

Lỗi

Mỗi lỗi API là một lớp con của EqvpsError với status (HTTP), code (chuỗi ổn định) và body. retry_after / retryAfter có giá trị khi máy chủ gửi nó.

Hai giới hạn gây ra phần lớn lỗi 429: một tài khoản chạy 2 lệnh cùng lúc và giữ tối đa 20 sandbox. SDK thử lại khi máy chủ cho biết cần chờ bao lâu; sau ba lần, bạn nhận ngoại lệ.

Khi nào không cần SDK

Ngôn ngữ nào có HTTP client cũng có thể gọi API trực tiếp; các endpoint nằm trong tệp OpenAPI tại https://eqvps.com/openapi.json. Tác tử trong Claude, Cursor hay các MCP client khác hoàn toàn không cần viết mã: máy chủ MCP có cùng bộ công cụ sandbox. Còn nếu chỉ muốn xem nó chạy thế nào, trang sandbox có bảng giá và gói dùng thử $1 cho tài khoản mới.