SDK Pythona do sandboxów w 5 minut: od pip install eqvps do pierwszego uruchomienia

Ten poradnik prowadzi od zera do działającego sandboxa w Pythonie. Uruchomisz odizolowaną mikro-VM na Firecrackerze, wykonasz w niej kod, zainstalujesz pakiet, przeniesiesz plik tam i z powrotem i puścisz coś długiego w tle. Każdy krok to kilka linijek do wklejenia.

Potrzebujesz Pythona 3.8 lub nowszego i konta EQVPS. SDK nie ma zależności.

1. Zdobądź token

Sandboxy są opłacane z salda konta, więc SDK potrzebuje tokenu konta. Strona łączenie konta pokazuje trzy sposoby jego uzyskania: panel, API albo serwer MCP. Potem umieść go w zmiennej środowiskowej:

export EQVPS_API_KEY="your-token"

Nie masz jeszcze salda? Nic nie szkodzi. Gdy nowe konto po raz pierwszy tworzy sandbox bez wystarczającego salda, dostaje 1 $ kredytu na sandboxy, ważnego 14 dni.

2. Zainstaluj SDK

pip install eqvps

3. Uruchom sandbox i wykonaj kod

Zapisz to jako hello.py i uruchom:

from eqvps import Sandbox

with Sandbox.create(tariff="small") as sb:
    print(sb.id)
    r = sb.run("import platform; print(platform.python_version())")
    print(r.exit_code, r.stdout)

Zobaczysz id sandboxa (sb_ i 24 kolejne znaki), a potem 0 3.12.x. Sandbox wystartował w około sekundę, wykonał kod i został usunięty, gdy skończył się blok with.

Co warto wiedzieć o wyniku:

• r.ok ma wartość true, gdy kod wyjścia to 0, a polecenie nie przekroczyło limitu czasu;
• niezerowy kod wyjścia nie jest wyjątkiem, więc sprawdzaj r.ok sam;
• stdout i stderr mają limit po 1 MiB, a r.truncated powie ci, czy wyjście zostało ucięte.

4. Zainstaluj pakiet i wykonaj polecenia powłoki

W sandboxie jesteś rootem w małym systemie Linux z Pythonem, Node.js, git i curl. exec wykonuje dowolne polecenie powłoki:

from eqvps import Sandbox

with Sandbox.create(tariff="small") as sb:
    sb.exec("pip install --quiet requests", timeout=55)
    r = sb.run("import requests; print(requests.get('https://example.com').status_code)")
    print(r.stdout)   # 200

Domyślny limit czasu to 30 sekund, a wywołanie synchroniczne trwa najwyżej 55. Duże instalacje lepiej puszczać jako zadanie w tle (krok 6).

5. Przenieś pliki tam i z powrotem

from eqvps import Sandbox

with Sandbox.create() as sb:
    sb.upload("/root/data.csv", "a,b\n1,2\n3,4\n")
    sb.run("""
import csv
rows = list(csv.DictReader(open('/root/data.csv')))
open('/root/sum.txt', 'w').write(str(sum(int(r['b']) for r in rows)))
""")
    print(sb.download_text("/root/sum.txt"))   # 6

Ścieżki muszą być bezwzględne. Jeden transfer jest ograniczony do 5 MB; download zwraca bajty, download_text napis.

6. Puść długie zadanie w tle

Przekaż background=True, a zamiast czekać dostaniesz zadanie. Nie ma ono limitu 55 sekund:

from eqvps import Sandbox

with Sandbox.create(tariff="standard") as sb:
    task = sb.exec("for i in 1 2 3 4 5; do echo step $i; sleep 20; done", background=True)
    result = task.wait(on_output=lambda out, err: print(out, end=""))
    print(result.state, result.exit_code)   # done 0

task.wait() odpytuje co 2 sekundy i wypisuje nowe wyjście, gdy tylko się pojawi. Możesz też sam wywoływać task.logs() albo zatrzymać zadanie przez task.kill(). Dopóki zadanie działa, sandbox nie jest usuwany za bezczynność.

Ile to kosztowało

Każdy blok with powyżej żył kilka sekund i został rozliczony za minimum 60 sekund. Na small to 0,00055 $ za blok, więc wszystkie pięć przykładów razem kosztuje około jednej trzeciej centa. Ceny wszystkich taryf, tryb trwały i limity wydatków znajdziesz w limitach i rozliczeniach sandboxów.

Gdy coś pójdzie nie tak

Błędy API to wyjątki, które możesz przechwycić:

from eqvps import Sandbox, InsufficientBalanceError, RateLimitError

try:
    with Sandbox.create() as sb:
        print(sb.run("print(1)").stdout)
except InsufficientBalanceError:
    print("Top up the balance")
except RateLimitError as e:
    print("Too many at once, retry in", e.retry_after)

SDK sam ponawia odpowiedzi 429 i 503 do trzech razy, gdy serwer poda, ile czekać. Wszystkie 11 klas błędów są w dokumentacji SDK.

Co dalej

• Te same kroki w JavaScripcie: SDK TypeScript do sandboxów w 5 minut.
• Niech model AI sam pisze kod i uruchamia go tutaj: pierwsze zadanie agenta w sandboxie.
• Taryfy, kredyt na próbę i co jest w sandboxie: strona sandboxów.