ה־SDK הוא שכבה דקה מעל ה־REST API של ארגזי החול. הוא חוסך לכם שלושה דברים: לבנות בקשות ביד, לנסות אותן שוב כשהפלטפורמה עמוסה, ולשכוח למחוק ארגז חול כשהקוד זורק חריגה. כל מה שכאן מתאים לגרסה 0.2.0 של שתי החבילות.
אם מעולם לא יצרתם ארגז חול, מדריך החיבור ב־5 דקות ייתן לכם קודם טוקן. מה זה ארגז חול ומה יש בתוכו מוסבר בארגזי חול.
התקנה והגדרה
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 אובייקט אפשרויות אחד.
| Python | TypeScript | ברירת מחדל | משמעות |
|---|---|---|---|
mode | mode | "ephemeral" | "ephemeral" (לפי שנייה) או "persistent" (לפי שעה שהתחילה, שומר את הדיסק) |
tariff | tariff | "small" | micro, small, standard, plus, pro, max |
idle_timeout | idleTimeout | 300 | שניות ללא פעילות לפני שארגז זמני נמחק, עד 3600 |
ttl | ttl | — | אורך חיים מרבי בשניות: עד 86400 לזמני, 2592000 לקבוע |
env | env | — | משתני סביבה לכל פקודה, נשמרים מוצפנים |
api_key, base_url | apiKey, baseUrl | משתני סביבה | מחליפים את EQVPS_API_KEY / EQVPS_API_URL |
timeout | timeoutMs | 70 שנ' | זמן קצוב HTTP לכל בקשה |
max_retries | maxRetries | 3 | ניסיונות חוזרים ב־429/503 |
המתודה 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) מריצה פקודת מעטפת: מחרוזת עוברת דרך bash -lc, ורשימה מורצת כ־argv בלי מעטפת.
שתיהן מחזירות ExecResult:
| שדה | משמעות |
|---|---|
exit_code | קוד היציאה של התהליך |
stdout, stderr | פלט, עד 1 MiB לכל זרם |
timed_out | הפקודה הגיעה לזמן הקצוב שלה |
truncated | הפלט נחתך |
duration_ms | כמה זמן רצה |
ok | exit_code == 0 ובלי חריגת זמן |
קריאה סינכרונית רצה 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) });
| מתודה | מה היא עושה |
|---|---|
task.logs() | stdout ו־stderr חדשים מאז הקריאה הקודמת |
task.status() | מצב בלי לצרוך פלט: running, done, failed, killed, timeout |
task.wait(timeout, poll_interval=2, on_output) | בודקת עד שהמשימה מסתיימת ומחזירה TaskResult |
task.kill() | עוצרת את המשימה ואת התהליכים שלה |
sb.task(id) / sb.tasks() | התחברות מחדש למשימה / רשימת משימות |
אם הזמן הקצוב של 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 מתמלא כשהשרת שולח אותו.
| מחלקה | HTTP | code נפוץ | מה לעשות |
|---|---|---|---|
AuthenticationError | 401 | unauthenticated | לבדוק את הטוקן |
InsufficientBalanceError | 402 | insufficient_balance | להטעין את היתרה |
NotFoundError | 404 | not_found | מזהה שגוי או קובץ שלא קיים |
SandboxPausedError | 409 | sandbox_paused | מושהה כי היתרה נגמרה; ממשיך אחרי טעינה |
SandboxDeletedError | 410 | sandbox_deleted | נמחק לצמיתות |
FileTooLargeError | 413 | file_too_large | לשמור העברות מתחת ל־5 MB |
ValidationError | 422 | invalid_request | לתקן את הפרמטרים |
RateLimitError | 429 | too_many_concurrent, too_many_tasks, rate_limited | להמתין ולנסות שוב |
BudgetExceededError | 429 | budget_exceeded | הגעתם למגבלת ההוצאה היומית או החודשית לארגזי חול |
CapacityError | 503 | capacity | לנסות שוב בעוד רגע או לבחור תעריף קטן יותר |
SandboxTimeoutError | — | request_timeout, wait_timeout | הזמן נגמר לבקשת ה־HTTP (או ל־wait), לא לפקודה |
רוב שגיאות ה־429 נובעות משתי מגבלות: חשבון מריץ 2 פקודות בו־זמנית ומחזיק עד 20 ארגזי חול. ה־SDK מנסה שוב כשהשרת אומר כמה לחכות; אחרי שלושה ניסיונות תקבלו את החריגה.
מתי לא צריך את ה־SDK
כל שפה עם לקוח HTTP יכולה לקרוא ל־API ישירות; נקודות הקצה מתוארות בקובץ OpenAPI בכתובת https://eqvps.com/openapi.json. סוכנים ב־Claude, ב־Cursor או בלקוחות MCP אחרים לא צריכים קוד בכלל: לשרת ה־MCP יש את אותם כלי ארגזי חול. ואם רק רוצים לראות איך זה עובד, בעמוד ארגזי החול יש את התעריפים ואת הניסיון ב־$1 לחשבונות חדשים.
תגובות
אין עדיין תגובות. היו הראשונים.