Справочник SDK

Пакеты @lizard-build/sdk (JS/TS) и lizard-sdk (Python) — это то, чем пользуются большинство агентов, приложений и скриптов для управления песочницами. На этой странице перечислены все классы и методы; пошаговое руководство см. в Quickstart.

Установка и аутентификация

npm install @lizard-build/sdk    # JavaScript / TypeScript
pip install lizard-sdk           # Python

SDK считывает LIZARD_API_KEY из окружения или принимает явный параметр apiKey в Sandbox.create / Sandbox.connect. Как создать ключ — в Quickstart → Аутентификация.

Каждая песочница также принадлежит проекту — расход учитывается по проекту, поэтому попытка создания без проекта будет отклонена.

`Lizard`

Клиент, привязанный к одному проекту, чтобы указывать проект один раз, а не при каждом вызове.

Метод	Описание
`new Lizard({ project, apiKey?, apiUrl?, timeoutMs? })`	Создать клиент. `project` обязателен — его ID, slug или имя (`Lizard(project=…)` в Python).
`lizard.create(template?, options?)`	Запустить песочницу в проекте клиента.
`lizard.connect(sandboxId)`	Подключиться к песочнице по ID, автоматически возобновив её, если была приостановлена.
`lizard.list()`	Получить список всех запущенных песочниц аккаунта.
`lizard.projectId()`	Разрешить ссылку на проект клиента в его ID (кэшируется после первого вызова).

const lizard = new Lizard({ project: 'my-project' });
const sandbox = await lizard.create('base');

lizard = Lizard(project="my-project")
sandbox = lizard.create("base")

Ссылка на проект, не соответствующая ни одному из доступных ключу, вызовет ошибку до запуска песочницы, перечислив доступные проекты.

В Python имена методов с подчёркиванием на конце (exec_) избегают перекрытия с зарезервированными словами, а свойства — в snake_case (sandbox_id) вместо camelCase (sandboxId). В примерах ниже используются имена JS/TS; точные сигнатуры смотрите в установленном Python-пакете.

`Sandbox`

Метод	Описание
`Sandbox.create(template?, options?)`	Запустить песочницу. `template` по умолчанию `'base'`; `options.project` задаёт проект для биллинга.
`Sandbox.connect(sandboxId)`	Подключиться к песочнице по ID, автоматически возобновив её, если была приостановлена.
`Sandbox.list()`	Получить список всех запущенных песочниц аккаунта.
`sandbox.sandboxId`	ID песочницы (`sandbox_id` в Python).
`sandbox.process.exec(cmd)`	Выполнить команду и дождаться завершения (`process.exec_` в Python). Возвращает `{ stdout, stderr, exitCode }`.
`sandbox.fs.write(path, data)`	Записать файл — строка или байты; создаёт родительские директории.
`sandbox.fs.read(path)`	Прочитать файл как UTF-8 строку.
`sandbox.fs.list(path)`	Список элементов директории → `[{ name, path, type, size }]`.
`sandbox.fs.makeDir(path)`	Создать директорию и все недостающие родители.
`sandbox.fs.remove(path)`	Удалить файл или директорию.
`sandbox.getHost(port)`	Зарегистрировать маршрут к `port` и вернуть публичный TLS-хост.
`sandbox.pause()`	Остановить гостевые vCPU и сохранить состояние в памяти хоста. Подробнее в статусах жизненного цикла перед тем как полагаться на паузу после исходного дедлайна.
`sandbox.resume()`	Возобновить приостановленную песочницу на месте.
`sandbox.setTimeout(ms)`	Задать оставшееся время жизни запущенной песочницы в миллисекундах (минимум 1000).
`sandbox.getInfo()`	Получить метаданные → `{ sandboxId, template, startedAt, endAt, … }`.
`sandbox.kill()`	Немедленно завершить песочницу и освободить ресурсы.

`Sandbox.create(template?, options?)`

Параметр	Тип	По умолчанию	Примечания
`template`	string	`'base'`	`'base'` или `'code-interpreter-v1'` — две поддерживаемые шаблоны
`project`	string	—	Обязательно. Проект для биллинга — его ID, slug или имя (`project` в Python). Не требуется при использовании клиента `Lizard`.
`projectId`	string	—	Точный ID проекта; пропускает разрешение `project`
`timeoutMs`	int	дефолт SDK 5 мин	Время жизни в мс
`region`	string	auto	Закрепить за регионом
`volumeName`	string	—	Подключить том по имени в `/workspace`
`volumeId`	string	—	Подключить том по ID для совместимости; для нового кода используйте `volumeName`
`apiKey`	string	переменная `LIZARD_API_KEY`	Явный API-ключ, переопределяет окружение

const sandbox = await Sandbox.create('base', { project: 'my-project', timeoutMs: 10 * 60 * 1000 });

`CodeSandbox`

Расширяет Sandbox стейтфул-ядром. Полное руководство в Интерпретатор кода.

Метод	Описание
`CodeSandbox.create(options?)`	Запустить интерпретатор кода (по умолчанию шаблон `code-interpreter-v1`). Принимает те же `project`, что и `Sandbox.create`.
`CodeSandbox.connect(sandboxId)`	Подключиться к (и автоматически возобновить) существующую песочницу интерпретатора.
`sandbox.runCode(code, opts?)`	Выполнить код в ядре. Возвращает `Execution`.
`sandbox.createContext(opts)`	Создать изолированное пространство имён — `{ language }`.
`sandbox.listContexts()`	Получить список контекстов песочницы.
`sandbox.restartContext(context)`	Очистить все переменные/состояние в контексте.
`sandbox.deleteContext(context)`	Освободить ресурсы контекста.

`runCode(code, opts?)`

Параметр	Описание
`language`	Среда выполнения для разового вызова — `'python'` (по умолчанию), `'javascript'` или `'bash'`. Взаимоисключающ с `context`.
`context`	Выполнить внутри конкретного изолированного контекста вместо дефолтного. Взаимоисключающ с `language`.
`onStdout` / `onStderr`	Потоковый вывод построчно по мере генерации.
`onResult`	Вызывается для каждого насыщенного результата (значения, сгенерированные изображения/диаграммы).
`onError`	Вызывается с `ExecutionError`, если код выбросил ошибку.

Возвращает Execution:

Поле	Описание
`stdout` / `stderr`	Захваченные потоки вывода
`results`	Насыщенные результаты (значения и любые сгенерированные изображения/диаграммы)
`error`	`ExecutionError` (`name`, `message`, `traceback`), если код выбросил ошибку
`executionCount`	Монотонный счётчик ядра

`Volume`

Подробности — в Persistent Volumes. Имена уникальны в проекте: строчные латинские буквы, цифры и дефисы, до 64 символов.

Новые тома принимают целые GB от 1 до 50, по умолчанию 5 (sizeGb в TypeScript, size_gb в Python). Настройки сервера могут менять предел. Существующие тома большего размера сохраняют размер; getOrCreate возвращает их без изменений.

API	Назначение
`Volume.create(projectId, name, options)`	Создать том; конфликт, если имя занято. `options.sizeGb` по умолчанию `5`.
`Volume.getOrCreate(projectId, name, options)`	Использовать том или создать его. Не меняет размер существующего тома. Python: `Volume.get_or_create`.
`Volume.list(projectId)`	Список томов проекта → `[{ id, name, sizeGb, status, attachedTo, … }]`.
`Volume.get(projectId, nameOrId)`	Найти том по имени или ID.
`Volume.delete(projectId, nameOrId)`	Удалить по имени или ID после отключения. Python: `Volume.remove`.
`volume.getInfo(projectId)`	Получить метаданные и статус подключения.
`volume.delete(projectId)`	Удалить том; сначала его нужно отключить.

См. также

Quickstart — установка, аутентификация и полное руководство.
Интерпретатор кода — руководство по CodeSandbox.
Persistent Volumes — руководство по Volume.

Статусы жизненного цикла

Перед тем как полагаться на паузу для сохранения сессии после исходного дедлайна, прочитайте известные проблемы. Пауза держит состояние гостя в памяти хоста; это не долговечный бэкап.

Быстрый старт Интерпретатор кода