Python SDK для пісочниць за 5 хвилин: від pip install eqvps до першого запуску

Цей посібник проведе від нуля до робочої пісочниці на Python. Ви запустите ізольовану мікро-VM на Firecracker, виконаєте в ній код, поставите пакет, передасте файл туди й назад і запустите щось довге у фоні. Кожен крок — кілька рядків, які можна вставити як є.

Потрібні Python 3.8 або новіший і акаунт EQVPS. SDK не має залежностей.

1. Отримайте токен

Пісочниці оплачуються з балансу акаунта, тож SDK потрібен токен акаунта. На сторінці підключення акаунта показано три способи його отримати: кабінет, API або MCP-сервер. Потім покладіть його у змінну оточення:

export EQVPS_API_KEY="your-token"

Балансу ще немає? Не страшно. Коли новий акаунт уперше створює пісочницю без достатнього балансу, він отримує $1 кредиту на пісочниці, що діє 14 днів.

2. Встановіть SDK

pip install eqvps

3. Запустіть пісочницю й виконайте код

Збережіть це як hello.py і запустіть:

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)

Ви побачите id пісочниці (sb_ і ще 24 символи), а потім 0 3.12.x. Пісочниця запустилася приблизно за секунду, виконала код і видалилася, коли закінчився блок with.

Що корисно знати про результат:

• r.ok дорівнює true, коли код повернення 0 і команда не вперлася в таймаут;
• ненульовий код повернення — не виняток, тож перевіряйте r.ok самі;
• stdout і stderr обмежені 1 MiB кожен, а r.truncated підкаже, якщо вивід обрізано.

4. Поставте пакет і виконайте команди shell

Усередині пісочниці ви root у невеликій Linux-системі з Python, Node.js, git і curl. exec виконує будь-яку команду shell:

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

Таймаут за замовчуванням — 30 секунд, а синхронний виклик може тривати не більше 55. Великі встановлення краще запускати фоновим завданням (крок 6).

5. Передайте файли туди й назад

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

Шляхи мають бути абсолютними. Одна передача обмежена 5 MB; download повертає байти, download_text — рядок.

6. Запустіть довге завдання у фоні

Передайте background=True, і замість очікування ви отримаєте завдання. Обмеження в 55 секунд у нього немає:

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() опитує завдання кожні 2 секунди й друкує новий вивід, щойно він з'являється. Можна й самому викликати task.logs() або зупинити завдання через task.kill(). Поки завдання працює, пісочниця не видаляється за бездіяльність.

Скільки це коштувало

Кожен блок with вище жив кілька секунд, і за нього списано мінімум у 60 секунд. На small це $0.00055 за блок, тож усі п'ять прикладів разом коштують близько третини цента. Ціни всіх тарифів, постійний режим і ліміти витрат — у розділі ліміти й оплата пісочниць.

Якщо щось пішло не так

Помилки API — це винятки, які можна перехопити:

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 сам повторює відповіді 429 і 503 до трьох разів, коли сервер повідомляє, скільки чекати. Усі 11 класів помилок перелічено в довіднику SDK.

Що далі

• Ті самі кроки на JavaScript: SDK для пісочниць на TypeScript за 5 хвилин.
• Нехай ШІ-модель сама пише код і запускає його тут: перше завдання агента в пісочниці.
• Тарифи, пробний кредит і що всередині пісочниці: сторінка пісочниць.