Αναφορά API για sandboxes: SDK Python και TypeScript

Το SDK είναι ένα λεπτό στρώμα πάνω από το REST API των sandboxes. Σας γλιτώνει από τρία πράγματα: να φτιάχνετε αιτήματα με το χέρι, να τα ξαναστέλνετε όταν η πλατφόρμα είναι απασχολημένη και να ξεχνάτε να διαγράψετε ένα sandbox όταν ο κώδικας πετάξει εξαίρεση. Όλα εδώ αντιστοιχούν στην έκδοση 0.2.0 και των δύο πακέτων.

Αν δεν έχετε φτιάξει ποτέ sandbox, ο οδηγός σύνδεσης σε 5 λεπτά σας δίνει πρώτα ένα token. Τι είναι ένα sandbox και τι περιέχει εξηγείται στη σελίδα Sandboxes.

Εγκατάσταση και ρύθμιση

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

Δημιουργία και εύρεση sandboxes

Το Sandbox.create(...) ξεκινά ένα sandbox, συνήθως σε περίπου ένα δευτερόλεπτο. Η Python δέχεται ονομαστικά ορίσματα, η TypeScript ένα αντικείμενο επιλογών.

Το Sandbox.connect(id) συνδέεται σε υπάρχον sandbox, συνήθως ένα μόνιμο που φτιάξατε χθες. Το Sandbox.list() επιστρέφει όλα τα sandboxes του λογαριασμού, ενεργά και σε παύση.

Ιδιότητες: 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) εκτελεί εντολή κελύφους: ένα string περνά από bash -lc, μια λίστα εκτελείται ως argv χωρίς κέλυφος.

Και τα δύο επιστρέφουν ExecResult:

Μια σύγχρονη κλήση διαρκεί το πολύ 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 φτάσει το δικό του χρονικό όριο, πετά SandboxTimeoutError, αλλά η εργασία συνεχίζει. Μια εργασία σε εξέλιξη εμποδίζει επίσης τη διαγραφή ενός εφήμερου sandbox λόγω αδράνειας.

Αρχεία και κατανάλωση

Το upload(path, content, mode=None) γράφει αρχείο σε απόλυτη διαδρομή και επιστρέφει το μέγεθός του. Το download(path) επιστρέφει bytes, το download_text(path) / downloadText(path) string. Μία μεταφορά περιορίζεται στα 5 MB.

Το usage() επιστρέφει δευτερόλεπτα λειτουργίας, δευτερόλεπτα CPU που χρησιμοποιήθηκαν, εξερχόμενα bytes, την τιμή ανά ώρα, billed_usd και estimated_total_usd. Το tariffs() είναι απλή συνάρτηση χωρίς κλειδί που επιστρέφει τις τρέχουσες τιμές και όρια. Οι κανόνες χρέωσης βρίσκονται στη σελίδα Όρια και χρέωση sandboxes.

Σφάλματα

Κάθε σφάλμα API είναι υποκλάση του EqvpsError με status (HTTP), code (σταθερό string) και body. Το retry_after / retryAfter συμπληρώνεται όταν το στέλνει ο server.

Τα περισσότερα 429 τα προκαλούν δύο όρια: ένας λογαριασμός εκτελεί 2 εντολές ταυτόχρονα και κρατά έως 20 sandboxes. Το SDK τα ξαναδοκιμάζει όταν ο server λέει πόσο να περιμένει· μετά από τρεις προσπάθειες παίρνετε την εξαίρεση.

Πότε δεν χρειάζεστε το SDK

Κάθε γλώσσα με HTTP client μπορεί να καλέσει το API απευθείας· τα endpoints βρίσκονται στο αρχείο OpenAPI στο https://eqvps.com/openapi.json. Οι πράκτορες σε Claude, Cursor ή άλλους MCP clients δεν χρειάζονται καθόλου κώδικα: ο MCP server έχει τα ίδια εργαλεία sandbox. Κι αν θέλετε απλώς να το δείτε να δουλεύει, η σελίδα των sandboxes δείχνει τα πακέτα και τη δοκιμή των $1 για νέους λογαριασμούς.