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 минут.
• Пусть ИИ-модель сама пишет код и запускает его здесь: первая задача агента в песочнице.
• Тарифы, пробный кредит и что внутри песочницы: страница песочниц.