คู่มืออ้างอิง Sandbox API: SDK สำหรับ Python และ TypeScript

SDK เป็นตัวห่อบาง ๆ ครอบ REST API ของ sandbox ช่วยให้คุณไม่ต้องทำสามอย่าง: สร้างคำขอด้วยมือ ลองใหม่เมื่อแพลตฟอร์มไม่ว่าง และลืมลบ sandbox เมื่อโค้ดโยน exception ทุกอย่างในหน้านี้ตรงกับเวอร์ชัน 0.2.0 ของทั้งสองแพ็กเกจ

ถ้าคุณยังไม่เคยสร้าง sandbox คู่มือเชื่อมต่อ 5 นาที จะช่วยให้คุณได้โทเค็นก่อน ส่วน sandbox คืออะไรและข้างในมีอะไร อธิบายไว้ใน แซนด์บ็อกซ์

ติดตั้งและตั้งค่า

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

โปรแกรมเดียวกันในทั้งสองภาษา: สร้าง sandbox รันโค้ด แล้วลบทิ้ง

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

Sandbox.create(...) เริ่ม sandbox ใหม่ ปกติใช้เวลาประมาณหนึ่งวินาที Python รับอาร์กิวเมนต์แบบระบุชื่อ ส่วน TypeScript รับออบเจ็กต์ตัวเลือกหนึ่งตัว

Sandbox.connect(id) เชื่อมต่อกับ sandbox ที่มีอยู่แล้ว โดยมากเป็น sandbox ถาวรที่คุณสร้างไว้เมื่อวาน Sandbox.list() ส่งคืน sandbox ทั้งหมดในบัญชี ทั้งที่กำลังรันและที่หยุดชั่วคราว

พร็อพเพอร์ตี: id (sb_ + อักขระฐานสิบหก 24 ตัว), mode, tariff, state (running, starting, paused, pausing, resuming, deleting, deleted), env_keys / envKeys (เฉพาะชื่อ ค่าจะไม่ถูกส่งกลับเด็ดขาด) และ info (ออบเจ็กต์ดิบ) ส่วน refresh() จะโหลดค่าเหล่านี้ใหม่

kill() ลบ sandbox และหยุดการคิดเงิน การเรียกกับ sandbox ที่ถูกลบไปแล้วไม่ถือเป็นข้อผิดพลาด

การรันโค้ด

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:

การเรียกแบบ synchronous รันได้ ไม่เกิน 55 วินาที ทั้งสองเมธอดยังรับ env สำหรับการเรียกครั้งนั้นได้ด้วย ซึ่งจะแทนที่ค่าที่ตั้งไว้ตอนสร้าง

งานที่ใช้เวลานาน: งานเบื้องหลัง

ส่ง background=True (TypeScript: { background: true }) แล้วคุณจะได้ Task ทันที งานนี้ไม่มีขีดจำกัด 55 วินาที และรันได้จนกว่าอายุของ sandbox จะหมด สูงสุด 8 งานต่อ 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) });

ถ้า wait ถึง timeout ของตัวเอง จะโยน SandboxTimeoutError แต่งานยังคงรันต่อ งานที่กำลังรันยังช่วยไม่ให้ sandbox ชั่วคราวถูกลบเพราะไม่มีกิจกรรมด้วย

ไฟล์และการใช้งาน

upload(path, content, mode=None) เขียนไฟล์ลงพาธแบบสัมบูรณ์และส่งคืนขนาดไฟล์ download(path) ส่งคืนไบต์ download_text(path) / downloadText(path) ส่งคืนสตริง การโอนแต่ละครั้งจำกัดที่ 5 MB

usage() ส่งคืนจำนวนวินาทีที่รัน วินาที CPU ที่ใช้ ไบต์ขาออก ราคาต่อชั่วโมง billed_usd และ estimated_total_usd ส่วน tariffs() เป็นฟังก์ชันธรรมดาที่ไม่ต้องใช้คีย์ และส่งคืนราคาและขีดจำกัดปัจจุบัน กฎการคิดเงินอยู่ใน ขีดจำกัดและการคิดเงินของ sandbox

ข้อผิดพลาด

ข้อผิดพลาดทุกตัวของ API เป็นคลาสย่อยของ EqvpsError ที่มี status (HTTP), code (สตริงที่คงที่) และ body ส่วน retry_after / retryAfter จะมีค่าเมื่อเซิร์ฟเวอร์ส่งมา

429 ส่วนใหญ่มาจากขีดจำกัดสองข้อ: บัญชีหนึ่งรัน คำสั่งพร้อมกันได้ 2 คำสั่ง และมี sandbox ได้สูงสุด 20 ตัว SDK จะลองใหม่เมื่อเซิร์ฟเวอร์บอกว่าต้องรอนานเท่าไร หลังลองครบสามครั้งคุณจะได้รับ exception

เมื่อไรไม่ต้องใช้ SDK

ภาษาใดก็ได้ที่มี HTTP client เรียก API ได้โดยตรง endpoint ทั้งหมดอยู่ในไฟล์ OpenAPI ที่ https://eqvps.com/openapi.json ส่วน agent ใน Claude, Cursor หรือ MCP client อื่น ๆ ไม่ต้องเขียนโค้ดเลย เพราะ เซิร์ฟเวอร์ MCP มีเครื่องมือ sandbox ชุดเดียวกัน และถ้าคุณแค่อยากเห็นมันทำงาน หน้า sandbox มีรายการแพ็กเกจและเครดิตทดลอง $1 สำหรับบัญชีใหม่