Справочник API песочниц: SDK для Python и TypeScript

SDK — тонкая обёртка над REST API песочниц. Он избавляет от трёх вещей: собирать запросы руками, повторять их, когда платформа занята, и забывать удалить песочницу, если код упал. Всё здесь соответствует версии 0.2.0 обоих пакетов.

Если вы ещё ни разу не создавали песочницу, руководство по подключению за 5 минут сначала поможет получить токен. Что такое песочница и что внутри — в разделе Песочницы.

Установка и настройка

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

Одна и та же программа на обоих языках: создать песочницу, выполнить код, удалить.

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.create(...) запускает песочницу, обычно примерно за секунду. В Python — именованные аргументы, в TypeScript — один объект опций.

Sandbox.connect(id) подключается к существующей песочнице — обычно к постоянной, созданной вчера. Sandbox.list() возвращает все песочницы аккаунта, работающие и на паузе.

Свойства: id (sb_ + 24 hex-символа), mode, tariff, state (running, starting, paused, pausing, resuming, deleting, deleted), env_keys / envKeys (только имена, значения не возвращаются) и info (сырой объект). refresh() перечитывает их.

kill() удаляет песочницу и останавливает тарификацию. Вызов для уже удалённой песочницы ошибкой не считается.

Выполнение кода

run(code, language="python", timeout=30) передаёт код через stdin в Python 3.12, Node.js 22 или bash ("python", "node", "bash"). exec(command, cwd=None, stdin=None, timeout=30) выполняет команду оболочки: строка идёт через bash -lc, список выполняется как argv без оболочки.

Оба возвращают ExecResult:

Синхронный вызов работает не дольше 55 секунд. Оба метода принимают и env на один вызов; он перекрывает значения, заданные при создании.

Долгие задачи: фоновый режим

Передайте background=True (в TypeScript { background: true }) — и сразу получите Task. У задачи нет ограничения в 55 секунд, она может работать до конца жизни песочницы. До 8 задач на песочницу.

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 истёк собственный таймаут, он бросает SandboxTimeoutError, но задача продолжает работать. Работающая задача также не даёт эфемерной песочнице удалиться по бездействию.

Файлы и расход

upload(path, content, mode=None) записывает файл по абсолютному пути и возвращает его размер. download(path) возвращает байты, download_text(path) / downloadText(path) — строку. Одна передача ограничена 5 МБ.

usage() возвращает секунды работы, использованные CPU-секунды, исходящие байты, цену в час, billed_usd и estimated_total_usd. tariffs() — обычная функция, ключ ей не нужен; возвращает текущие цены и лимиты. Правила тарификации — на странице Лимиты и оплата песочниц.

Ошибки

Каждая ошибка API — подкласс EqvpsError с полями status (HTTP), code (стабильная строка) и body. retry_after / retryAfter заполнено, если сервер его прислал.

Большинство 429 вызывают два лимита: аккаунт выполняет 2 команды одновременно и держит до 20 песочниц. SDK повторяет такие запросы, если сервер сообщил, сколько ждать; после трёх попыток вы получите исключение.

Когда SDK не нужен

Любой язык с HTTP-клиентом может обращаться к API напрямую; эндпоинты описаны в файле OpenAPI по адресу https://eqvps.com/openapi.json. Агентам в Claude, Cursor и других MCP-клиентах код не нужен вовсе: у MCP-сервера те же инструменты песочниц. А если хочется просто посмотреть, как это работает, на странице песочниц есть тарифы и пробный $1 для новых аккаунтов.