# Жизненный цикл песочницы

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

## Модель состояний[​](#state-model "Прямая ссылка на Модель состояний")

Поле `status` в ответе `GET /v1/sandboxes/{id}` принимает следующие значения:

| Состояние     | Значение                                                                     | Что делать                                                                        |
| ------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `starting`    | Среда выполнения загружается                                                 | Опросить ресурс до `running` или `failed`                                         |
| `running`     | Среда выполнения доступна для команд, файлов, терминалов и открытых сервисов | Выполнить работу, остановить, гибернировать или удалить                           |
| `stopping`    | VM остановлена, постоянное состояние диска финализируется                    | Дождаться `stopped` перед зависимой работой                                       |
| `stopped`     | Файловая система сохранена, но процессы и память — нет                       | Выполнить холодный запуск через `resume`                                          |
| `resuming`    | Сохраненная файловая система восстанавливается и загружается                 | Опросить ресурс до `running` или `failed`                                         |
| `hibernating` | Создается полный снимок VM                                                   | Дождаться `hibernated`                                                            |
| `hibernated`  | Сохранены диск, память, CPU и состояние процессов                            | Восстановить состояние VM через `wake`                                            |
| `failed`      | Среда выполнения не смогла перейти или остаться в рабочем состоянии          | Проверить `error_reason` и вкладку *События*, затем перезапустить или пересоздать |

Готовность подготовки не совпадает с состоянием среды выполнения. Песочница может уже быть `running`, пока `provisioning.status` остается `in_progress`. Перед использованием клонированного репозитория или другого подготовленного артефакта дождитесь `provisioning.status: "ready"`.

Обычные переходы:

```
create → starting → running

running → stopping → stopped → resuming → running
running → hibernating → hibernated → running

starting/running/transition → failed → running
любое существующее состояние → delete → ресурс больше не существует
```

Последний переход `failed → running` — восстановительный перезапуск, а не обычная перезагрузка исправной песочницы.

## Остановка, гибернация или удаление[​](#stop-hibernate-or-delete "Прямая ссылка на Остановка, гибернация или удаление")

| Действие   | Что сохраняется                                       | Что теряется                                                                                   | Возврат                 |
| ---------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------- |
| Остановка  | Ресурс песочницы и состояние файловой системы         | Работающие процессы и состояние в памяти                                                       | Возобновление           |
| Гибернация | Файловая система, память VM, CPU и процессы           | Активным сетевым соединениям все равно может потребоваться восстановление на уровне приложения | Пробуждение             |
| Удаление   | Ничего из данных, принадлежащих только этой песочнице | Ресурс песочницы и его данные                                                                  | Создать новую песочницу |

Используйте *Остановить* в меню действий песочницы, если в дальнейшем допустима холодная загрузка. Возобновленная песочница может быть размещена на подходящем узле и принимать необязательные новые значения vCPU или RAM.

Используйте *В гибернацию*, когда важно продолжить работу из состояния в памяти. Снимок памяти принадлежит записанному узлу, поэтому пробуждение также зависит от его доступности.

Используйте *Удалить*, только когда песочница и ее данные больше не нужны. Публичный API не восстанавливает удаленную песочницу. Если состояние может пригодиться повторно, сначала сохраните его как шаблон.

Личную песочницу можно сохранить как шаблон. Видимость `private` созданного шаблона действует на весь аккаунт: другие участники организации смогут создать песочницу из снимка корневой файловой системы. В снимке могут остаться файлы, настройки и секреты, записанные на диск исходной песочницы. Перед сохранением проверьте содержимое файловой системы.

## Изменение состояния в веб-интерфейсе[​](#change-state-in-the-web-ui "Прямая ссылка на Изменение состояния в веб-интерфейсе")

Откройте меню действий песочницы:

* для активной песочницы доступны *Остановить* и *В гибернацию*;
* для остановленной — *Запустить*;
* для песочницы в гибернации — *Разбудить*;
* для песочницы со сбоем — *Перезапустить*;
* после подтверждения ресурс можно *Удалить*.

Страница песочницы опрашивает переходные состояния и открывает вкладки среды выполнения после перехода в `running`. Вкладки *Настройки* и *События* остаются доступны для стабильных состояний `stopped`, `hibernated` и `failed`.

## Изменение состояния через API[​](#change-state-through-the-api "Прямая ссылка на Изменение состояния через API")

Для каждого действия жизненного цикла предназначен отдельный эндпоинт:

```
# Running → Stopped
curl --fail-with-body --silent --show-error \
  --request POST "$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID/stop" \
  --header "Authorization: Bearer $JUSTRUN_PAT" |
  jq

# Stopped → Running
curl --fail-with-body --silent --show-error \
  --request POST "$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID/resume" \
  --header "Authorization: Bearer $JUSTRUN_PAT" \
  --header "Content-Type: application/json" \
  --data '{}' |
  jq

# Running → Hibernated
curl --fail-with-body --silent --show-error \
  --request POST "$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID/hibernate" \
  --header "Authorization: Bearer $JUSTRUN_PAT" |
  jq

# Hibernated → Running
curl --fail-with-body --silent --show-error \
  --request POST "$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID/wake" \
  --header "Authorization: Bearer $JUSTRUN_PAT" |
  jq
```

После действия опрашивайте сам ресурс, а не считайте любой переход завершенным при получении ответа:

```
curl --fail-with-body --silent --show-error \
  "$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID" \
  --header "Authorization: Bearer $JUSTRUN_PAT" |
  jq '{id, status, error_reason, started_at, stopped_at}'
```

После остановки ресурс может ненадолго показывать `stopping`, пока финализируется постоянное состояние. Во время возобновления или пробуждения он может находиться в переходном состоянии, пока среда выполнения загружается.

## Автоматическая пауза и пробуждение[​](#automatic-pause-and-wake "Прямая ссылка на Автоматическая пауза и пробуждение")

Поведение жизненного цикла настраивается для каждой песочницы:

* `idle_pause_ms` ставит работающую песочницу на паузу после окна простоя;
* `idle_pause_action` выбирает `stop` или `hibernate`;
* `wake_on_request` позволяет подходящему входящему запросу вернуть песочницу в состояние `running`;
* `timeout_ms` задает окно истечения, которое запускается заново при возобновлении или пробуждении.

Пробуждение по запросу штатно пробуждает песочницу в гибернации. Остановленную песочницу можно возобновить внутри запроса только тогда, когда это разрешено в инсталляции и существует актуальная теплая локальная копия. В противном случае запрос получает повторяемую ошибку недоступности, а клиент должен явно вызвать `resume`.

Значения по умолчанию и семантика PATCH описаны в разделе [Настройка песочницы](/sandboxes/configure-a-sandbox.md).

## Границы и ошибки[​](#failure-boundaries "Прямая ссылка на Границы и ошибки")

* Действие из неверного состояния возвращает HTTP `409`. Для `stopped` используйте `resume`, а для `hibernated` — `wake`.
* Возобновление может вернуть HTTP `503`, если нет здорового узла с достаточными ресурсами. Повторите то же возобновление; не создавайте замену, если это не является желаемым результатом.
* `restart` принимается только для `failed` или прерванного `stopping` и требует доступного локального датасета. Это не перезагрузка исправной работающей песочницы.
* Действия жизненного цикла могут конфликтовать с сохранением шаблона. Дождитесь завершения сохранения и повторите запрос.
* Песочницу после сбоя не всегда можно восстановить. Если перезапуск продолжает завершаться ошибкой, изучите вкладку *События* и `error_reason`, сохраните внешние данные и пересоздайте песочницу.

## Связанные разделы[​](#related "Прямая ссылка на Связанные разделы")

* [Настройка песочницы](/sandboxes/configure-a-sandbox.md)
* [Команды, процессы и терминалы](/sandboxes/commands-processes-and-terminals.md)
* [Наблюдаемость и диагностика](/sandboxes/observability-and-troubleshooting.md)
* [Справочник REST API](/api-reference/rest.md)
* [Протоколы песочницы для обмена данными в реальном времени](/api-reference/realtime.md)
