Sandbox API başvurusu: Python ve TypeScript SDK

SDK, sandbox REST API'si üzerinde ince bir katmandır. Sizi üç şeyden kurtarır: istekleri elle kurmak, platform meşgulken yeniden denemek ve kod istisna fırlattığında sandbox'ı silmeyi unutmak. Buradaki her şey iki paketin 0.2.0 sürümüne karşılık gelir.

Daha önce hiç sandbox oluşturmadıysanız 5 dakikalık bağlantı rehberi önce size bir token verir. Sandbox'ın ne olduğu ve içinde ne bulunduğu Sandbox'lar sayfasında anlatılıyor.

Kurulum ve yapılandırma

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

İki dilde aynı program: bir sandbox oluştur, kod çalıştır, sil.

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 oluşturma ve bulma

Sandbox.create(...) bir sandbox başlatır, genellikle yaklaşık bir saniyede. Python isimli argümanlar, TypeScript tek bir seçenek nesnesi alır.

Sandbox.connect(id) mevcut bir sandbox'a bağlanır; genellikle dün oluşturduğunuz kalıcı bir sandbox'a. Sandbox.list() hesaptaki çalışan ve duraklatılmış tüm sandbox'ları döndürür.

Özellikler: id (sb_ + 24 onaltılık karakter), mode, tariff, state (running, starting, paused, pausing, resuming, deleting, deleted), env_keys / envKeys (yalnızca adlar, değerler hiç geri gelmez) ve info (ham nesne). refresh() bunları yeniden yükler.

kill() sandbox'ı siler ve faturalamayı durdurur. Zaten silinmiş bir sandbox için çağırmak hata sayılmaz.

Kod çalıştırma

run(code, language="python", timeout=30) kodu stdin üzerinden Python 3.12, Node.js 22 veya bash'e gönderir ("python", "node", "bash"). exec(command, cwd=None, stdin=None, timeout=30) bir kabuk komutu çalıştırır: dize bash -lc üzerinden geçer, liste kabuk olmadan argv olarak çalıştırılır.

İkisi de bir ExecResult döndürür:

Senkron bir çağrı en fazla 55 saniye sürer. İki metot da yalnızca o çağrı için env alır; oluşturma sırasında belirlenen değerlerin yerine geçer.

Uzun işler: arka plan görevleri

background=True (TypeScript: { background: true }) verin, hemen bir Task alırsınız. 55 saniye sınırı yoktur ve sandbox'ın ömrü bitene kadar çalışabilir. Sandbox başına en fazla 8 görev.

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 kendi zaman aşımına ulaşırsa SandboxTimeoutError fırlatır, ama görev çalışmaya devam eder. Çalışan bir görev, geçici bir sandbox'ın hareketsizlik yüzünden silinmesini de engeller.

Dosyalar ve kullanım

upload(path, content, mode=None) mutlak bir yola dosya yazar ve boyutunu döndürür. download(path) bayt, download_text(path) / downloadText(path) dize döndürür. Tek bir aktarım 5 MB ile sınırlıdır.

usage() çalışma saniyelerini, kullanılan CPU saniyelerini, giden baytları, saatlik fiyatı, billed_usd ve estimated_total_usd değerlerini döndürür. tariffs() anahtar gerektirmeyen basit bir fonksiyondur ve güncel fiyatları ve sınırları döndürür. Faturalama kuralları Sandbox sınırları ve faturalama sayfasında.

Hatalar

Her API hatası, status (HTTP), code (sabit dize) ve body alanlarına sahip bir EqvpsError alt sınıfıdır. Sunucu gönderdiğinde retry_after / retryAfter doldurulur.

429'ların çoğuna iki sınır yol açar: bir hesap aynı anda 2 komut çalıştırır ve en fazla 20 sandbox tutar. SDK, sunucu ne kadar bekleneceğini söylediğinde bunları yeniden dener; üç denemeden sonra istisnayı alırsınız.

SDK'ya ne zaman gerek yok

HTTP istemcisi olan her dil API'yi doğrudan çağırabilir; uç noktalar https://eqvps.com/openapi.json adresindeki OpenAPI dosyasında. Claude, Cursor veya diğer MCP istemcilerindeki ajanların hiç koda ihtiyacı yok: MCP sunucusu aynı sandbox araçlarına sahip. Yalnızca nasıl çalıştığını görmek istiyorsanız, sandbox sayfası tarifeleri ve yeni hesaplar için $1'lık denemeyi gösterir.