5 dakikada sandbox için TypeScript SDK: npm i @eqvps/sdk'den ilk çalıştırmaya

Bu rehber JavaScript veya TypeScript'ten bir sandbox çalıştırır. Yalıtılmış bir Firecracker microVM başlatacak, üç dilde kod çalıştıracak, dosya taşıyacak ve uzun bir işin çıktısını izleyeceksiniz. Her adım kısa bir kod parçasıdır.

Node.js 18+ (ya da Deno veya Bun) ve bir EQVPS hesabı gerekir.

1. Token alın

SDK, sıradan bir hesap token'ıyla kimlik doğrular. Hesabınızı bağlama sayfası onu panelden, API'den veya MCP sunucusundan nasıl alacağınızı gösterir.

export EQVPS_API_KEY="your-token"

Bakiyesi olmayan yeni bir hesap, ilk kez sandbox oluşturduğunda 1 $ sandbox kredisi alır. Bu, bu rehberi defalarca karşılar.

2. SDK'yı kurun

npm i @eqvps/sdk

Örnekler ES modüllerini ve üst düzey await kullanır. Bunları .mjs dosyası olarak ya da .ts olarak kaydedip npx tsx ile çalıştırın.

3. Sandbox başlatın ve kod çalıştırın

import { Sandbox } from "@eqvps/sdk";

await Sandbox.with({ tariff: "small" }, async (sb) => {
  console.log(sb.id);
  const r = await sb.run("import platform; print(platform.python_version())");
  console.log(r.exit_code, r.stdout);
});

Çıktı sandbox kimliğidir (sb_ ve ardından 24 karakter), sonra 0 3.12.x. Sandbox.with, geri çağırma bittiğinde sandbox'ı siler, hata fırlatsa bile.

Varsayılan dil Python'dur. Diğer ikisi tek bir seçenek uzaklıktadır:

await Sandbox.with({}, async (sb) => {
  const js = await sb.run("console.log(process.version)", { language: "node" });
  const sh = await sb.run("uname -r && nproc", { language: "bash" });
  console.log(js.stdout, sh.stdout);
});

Başarısız olan bir betik hata fırlatmaz. exit_code 0 olduğunda ve komut zaman aşımına uğramadığında true olan r.ok değerini kontrol edin.

4. Kabuk komutları ve paketler

exec bir kabuk metni veya argv dizisi alır. Sandbox'ın internet erişimi vardır, bu yüzden npm ve pip kurulumları çalışır:

await Sandbox.with({ tariff: "small" }, async (sb) => {
  await sb.exec("mkdir -p /root/app && cd /root/app && npm init -y && npm i lodash", { timeout: 55 });
  const r = await sb.exec(["node", "-e", "console.log(require('/root/app/node_modules/lodash').VERSION)"]);
  console.log(r.stdout);
});

Eşzamanlı bir çağrı en fazla 55 saniye sürebilir. Daha uzun her şey arka plan görevine gider (6. adım).

5. Dosyalar

await Sandbox.with({}, async (sb) => {
  await sb.upload("/root/input.json", JSON.stringify({ values: [3, 5, 8] }));
  await sb.run("import json; d = json.load(open('/root/input.json')); open('/root/out.txt', 'w').write(str(sum(d['values'])))");
  console.log(await sb.downloadText("/root/out.txt"));   // 16
});

upload bir metin veya Uint8Array alır. download bir Uint8Array, downloadText ise metin döndürür. Tek bir aktarım 5 MB ile sınırlıdır.

6. Canlı çıktılı uzun işler

await Sandbox.with({ tariff: "standard" }, async (sb) => {
  const task = await sb.exec("for i in 1 2 3 4 5; do echo step $i; sleep 20; done", { background: true });
  const res = await task.wait({ onOutput: (out) => process.stdout.write(out) });
  console.log(res.state, res.exit_code);   // done 0
});

Görev hemen döner ve 55 saniyelik sınırı yoktur. wait varsayılan olarak her 2 saniyede bir sorgular (pollIntervalMs bunu değiştirir). task.kill() görevi durdurur; sb.task(id) başka bir süreçten yeniden bağlanır.

Hatalar

import { Sandbox, InsufficientBalanceError, RateLimitError } from "@eqvps/sdk";

try {
  await Sandbox.with({}, async (sb) => console.log((await sb.run("print(1)")).stdout));
} catch (e) {
  if (e instanceof InsufficientBalanceError) console.log("Top up the balance");
  else if (e instanceof RateLimitError) console.log("Busy, retry in", e.retryAfter);
  else throw e;
}

Sunucu Retry-After gönderdiğinde SDK, 429 ve 503'ü kendiliğinden üç kereye kadar yeniden dener. En yaygın 429, bir hesapta aynı anda ikiden fazla komut çalıştırmaktan kaynaklanır. Tüm sınıflar SDK başvurusunda yer alır.

Bu rehberin maliyeti

Her örnek birkaç saniye yaşadı ve 60 saniyelik asgari süre üzerinden faturalandı: small tarifesinde 0,00055 $, standard tarifesinde 0,0011 $. 6. adımdaki iş standard üzerinde yaklaşık 100 saniye sürdü, yani yaklaşık 0,002 $. Hepsi birlikte bir sentin çok altında kalır. Tam fiyat listesi sandbox sınırları ve faturalama sayfasındadır.

Sonraki adımlar

• Aynısı Python'da: 5 dakikada sandbox için Python SDK.
• Bir model bağlayın ve kendi kodunu çalıştırmasına izin verin: sandbox'ta ilk ajan göreviniz.
• Tarifeler ve 1 $'lık deneme: sandbox sayfası.