<span id="sandboxes" />

# Песочницы

**Песочница** — это изолированный микро-VM Firecracker, который вы запускаете по требованию, выполняете внутри код и удаляете по завершении. Каждая песочница — полноценная Linux-среда со своей файловой системой, сетью и пространством процессов — загружается за миллисекунды, а не минуты.

Песочницы — вычислительная основа для ИИ-агентов, интерпретаторов кода, оценок и задач в стиле CI на Lizard. Если [сервис](https://lizard.build/ru/docs/concepts/architecture) — это долгоживущее развертывание, привязанное к репозиторию, то песочница — **эфемерная, программная и одноразовая** — создавайте песочницу для каждой задачи в пределах емкости вашего аккаунта.

```ts
import { Sandbox } from '@lizard-build/sdk';

const sandbox = await Sandbox.create('base', { project: 'my-project' });
const { stdout } = await sandbox.process.exec('echo "hello from Lizard"');
console.log(stdout);            // hello from Lizard
await sandbox.kill();
```

<span id="when-to-use-a-sandbox" />

## Когда использовать песочницу

| Используйте **песочницу**, когда… | Используйте **сервис**, когда… |
|---|---|
| Агенту нужно выполнить недоверенный или сгенерированный код | Вы развертываете приложение, которое должно работать постоянно |
| Нужен чистый, одноразовый Linux за каждой задачей | Нужен стабильный URL `<name>.<region>.onlizard.com` и TLS |
| Нужно распараллелить множество изолированных задач | У вас есть один всегда работающий процесс |
| Нагрузка кратковременная или приостанавливается | Нагрузка привязана к git и автоматически переразвертывается |

После того как агент создал работающее приложение внутри песочницы, вы можете продвинуть его в постоянный сервис с помощью [`lizard up`](https://lizard.build/ru/docs/deploy/upload) — без Dockerfile.

<span id="what-makes-them-fast" />

## Почему они быстрые

- **Микровычислители Firecracker** — отдельный Linux-гость для каждой песочницы. У рантаймов приложений разные правила изоляции. Аппаратная виртуализация отделяет гостя от хоста. Контролируйте учетные данные и сетевой доступ для кода, которому не доверяете.
- **Приостановка и возобновление** — приостановка замораживает vCPU микро-VM. Память, файловая система и запущенные процессы сохраняются как есть, поэтому возобновление продолжает ровно с того же места — без переустановки пакетов или повторного прогрева кэшей. Именно это позволяет долгим сессиям агентов выживать при отдельных вызовах. Состояние хранится в памяти хоста, а не на диске, поэтому не выживает при сбое хоста. См. [приостановка и возобновление](https://lizard.build/ru/docs/sandboxes/quickstart#pause-and-resume).
- **Загрузка из шаблона** — каждый узел заранее создает эталонный снимок для каждого шаблона, поэтому `create` — это восстановление, а не холодная загрузка.

<span id="templates" />

## Шаблоны

Песочница загружается из **шаблона** (в панели управления он также называется *снимком*). Доступны два встроенных шаблона:

| Шаблон | Содержимое | Подходит для |
|---|---|---|
| `base` | Debian Linux, Node.js 26 и Lizard CLI | Командные оболочки общего назначения и среды сборки |
| `code-interpreter-v1` | Python 3.14 + Node.js 26, с HTTP API выполнения кода на порту 8080 | ИИ-интерпретаторы кода — управляйте через [`CodeSandbox`](https://lizard.build/ru/docs/sandboxes/code-interpreter) |

`base` — по умолчанию. Публичный API создания принимает эти два имени шаблона. Загрузка пользовательских шаблонов через этот API не предусмотрена.

<span id="lifecycle" />

## Жизненный цикл

Песочница переходит между тремя состояниями:

```
create ──▶ running ⇄ paused ──▶ stopped
                              (killed or expired)
```

- **running** — гость может выполнять команды, работать с файлами и обслуживать открытые порты.
- **paused** — vCPU остановлены. Память гостя и состояние процессов остаются на хосте; это не устойчивый снимок или резервная копия.
- **stopped** — песочница завершена через удаление или истечение срока. Её локальная файловая система больше недоступна.

SDK по умолчанию отправляет время жизни 5 минут. При прямом вызове API создания можно передать `timeoutMs: 0`, чтобы отключить ограничение срока действия. Передавайте явный таймаут, когда скрипт должен вести себя одинаково на всех клиентах, и освобождайте песочницу по завершении задачи. Команды не сбрасывают время жизни.

Приостановка предназначена для сохранения оставшегося времени работы. Проверьте [текущую проблему жизненного цикла](https://lizard.build/ru/docs/platform/known-issues#sandbox-pause-and-expiration) перед тем, как полагаться на приостановку дольше исходного срока. Для хранения постоянных файлов используйте [том](https://lizard.build/ru/docs/sandboxes/volumes); приостановленный гость не выживает при сбое хоста.

<span id="resources--limits" />

## Ресурсы и лимиты

Каждая песочница работает на фиксированных **4 vCPU / 4096 MiB RAM**. Публичный API создания не имеет настройки размера для каждой песочницы. Каждая песочница наследует ресурсы своего шаблона.

Регион выбирается автоматически с учётом доступных ресурсов; в панели управления можно указать нужный регион. Для квот приложений и доступных ресурсов песочниц могут действовать разные правила. См. [лимиты](https://lizard.build/ru/docs/platform/limits).

<span id="ways-to-drive-sandboxes" />

## Способы управления песочницами

| Способ управления | Подходит для | Начните здесь |
|---|---|---|
| **SDK** (JS / Python) | Агенты, приложения и скрипты — включая с сохранением состояния, многоязычное выполнение через [`CodeSandbox`](https://lizard.build/ru/docs/sandboxes/code-interpreter) | [Быстрый старт](https://lizard.build/ru/docs/sandboxes/quickstart) · [Справочник SDK](https://lizard.build/ru/docs/sandboxes/sdk-reference) |
| **Панель управления** | Ручное создание, терминал, SSH, мониторинг | [Панель управления](https://lizard.build/ru/docs/sandboxes/dashboard) |