# Настройка песочницы

Настройте песочницу после создания, не заменяя ее файловую систему. Метаданные и поведение жизненного цикла изменяются через `PATCH`, а vCPU и RAM — во время холодного цикла остановки и возобновления.

## Перед началом[​](#before-you-begin "Прямая ссылка на Перед началом")

Нужен доступ к песочнице в активном аккаунте. Для REST требуется персональный токен с правами `full`.

Перед подготовкой PATCH получите текущее состояние ресурса:

```
curl --fail-with-body --silent --show-error \
  "$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID" \
  --header "Authorization: Bearer $JUSTRUN_PAT" |
  jq '{
    id,
    name,
    status,
    vcpu,
    ram_mb,
    disk_mb,
    metadata,
    env_vars,
    storage_access,
    wake_on_request,
    idle_pause_ms,
    idle_pause_action,
    timeout_ms,
    expires_at
  }'
```

Сохраните полные текущие объекты `metadata` и `env_vars`, если остальные записи должны остаться. Поля PATCH заменяют эти объекты целиком, а не объединяют их по ключам.

## Настройка через веб-интерфейс[​](#configure-through-the-web-ui "Прямая ссылка на Настройка через веб-интерфейс")

1. Откройте песочницу и выберите *Настройки*.
2. При необходимости измените отображаемое имя в разделе *Название и ID*.
3. В разделе *Ресурсы* выберите vCPU и память, затем нажмите *Применить*. Интерфейс выполнит холодный перезапуск: остановку, затем возобновление с новыми значениями.
4. В разделе *Доступ к хранилищу* выберите *Нет доступа*, *Чтение* или *Чтение/запись*, если хранилище аккаунта доступно в инсталляции.
5. В разделе *Автопауза, автозавершение и пробуждение* настройте пробуждение по запросу, автопаузу и ее действие, а также автозавершение по времени.
6. На вкладке *Переменные окружения* добавьте, измените или удалите переменные.

Вкладки *Настройки*, *Переменные окружения* и *События* доступны, когда песочница остановлена, находится в гибернации или завершилась с ошибкой. Вкладкам среды выполнения требуется состояние `running`.

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

## Настройка через REST API[​](#configure-through-the-rest-api "Прямая ссылка на Настройка через REST API")

Отправляйте только изменяемые настройки, но передавайте полное желаемое содержимое `metadata` и `env`:

```
curl --fail-with-body --silent --show-error \
  --request PATCH "$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID" \
  --header "Authorization: Bearer $JUSTRUN_PAT" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "staging-worker",
    "metadata": {
      "environment": "staging",
      "owner": "platform"
    },
    "env": {
      "LOG_LEVEL": "info",
      "FEATURE_FLAG": "enabled"
    },
    "storage_access": "ro",
    "wake_on_request": true,
    "idle_pause_ms": 900000,
    "idle_pause_action": "hibernate",
    "timeout_ms": 86400000
  }' |
  jq '{
    id,
    name,
    metadata,
    env_vars,
    storage_access,
    wake_on_request,
    idle_pause_ms,
    idle_pause_action,
    timeout_ms,
    expires_at
  }'
```

Поддерживаемые поля PATCH:

| Поле                | Значения и поведение                                                              |
| ------------------- | --------------------------------------------------------------------------------- |
| `name`              | Отображаемое имя; `null` удаляет его                                              |
| `metadata`          | Полный объект со строковыми значениями; `{}` удаляет все метаданные               |
| `env`               | Полный объект окружения; `{}` удаляет все переменные                              |
| `storage_access`    | `none`, `ro` или `rw`; для `ro` и `rw` хранилище аккаунта должно быть включено    |
| `wake_on_request`   | Логическое значение, управляющее допустимыми попытками пробуждения внутри запроса |
| `idle_pause_ms`     | Окно простоя не меньше `30000`; `null` отключает автопаузу                        |
| `idle_pause_action` | `stop`, `hibernate` или `null` для значения инсталляции по умолчанию              |
| `timeout_ms`        | Время до истечения от момента PATCH; `null` убирает истечение                     |

Для новых песочниц, созданных через собственный API, по умолчанию включено пробуждение по запросу, задано часовое окно простоя и выбрано действие `hibernate`. Явные значения при создании заменяют эти значения по умолчанию, поэтому существующие песочницы могут отличаться.

Изменение доступа к хранилищу ротирует токен хранилища песочницы и обновляет `JR_STORAGE_TOKEN` и `JR_STORAGE_URL` в сохраненном окружении. Отзыв через `none` делает предыдущий токен недействительным и удаляет эти переменные. Обращайтесь с их значениями как с секретами: не копируйте их в документацию, логи или систему контроля версий.

## Изменение vCPU и RAM[​](#change-vcpu-and-ram "Прямая ссылка на Изменение vCPU и RAM")

vCPU и RAM не являются полями PATCH и не изменяются на работающей среде выполнения. Остановите песочницу и передайте необязательные переопределения при возобновлении:

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

# Опросите GET /v1/sandboxes/{id} до состояния stopped.

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 '{"vcpu": 2, "ram_mb": 2048}' |
  jq '{id, status, vcpu, ram_mb}'
```

Сервер принимает 1–8 vCPU и 128–8192 МиБ RAM. Если переопределение не указано, сохраняется текущее значение. При холодном перезапуске теряются процессы и состояние в памяти, но сохраняется остановленная файловая система.

Размер корневого диска, шаблон и его версия, Unix-пользователь по умолчанию, клонирование репозитория, секреты, MCP-серверы, навыки, объявленные при создании открытые порты и другие компоненты подготовки не являются обычными PATCH-настройками. Настраивайте их там, где ими управляют, или создайте новую песочницу. Корневой диск нельзя уменьшить или изменить после создания.

## Проверка результата[​](#verify-the-result "Прямая ссылка на Проверка результата")

PATCH возвращает HTTP `200` и обновленную песочницу. Если ресурс мог параллельно изменить другой клиент, получите его еще раз:

```
curl --fail-with-body --silent --show-error \
  "$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID" \
  --header "Authorization: Bearer $JUSTRUN_PAT" |
  jq '{
    status,
    name,
    vcpu,
    ram_mb,
    metadata,
    env_vars,
    storage_access,
    wake_on_request,
    idle_pause_ms,
    idle_pause_action,
    timeout_ms,
    expires_at
  }'
```

После изменения ресурсов дождитесь `status: "running"` и проверьте `vcpu` и `ram_mb`. После изменения окружения запустите новый процесс и выводите только имена переменных или безопасные несекретные значения.

## Рекомендации для рабочей среды[​](#production-considerations "Прямая ссылка на Рекомендации для рабочей среды")

* Не помещайте учетные данные в `env`. Используйте [Секреты](/secrets.md) и выдавайте рабочей нагрузке только необходимые права.
* `metadata` и `env` заменяются целиком. Используйте схему «чтение — изменение — запись», чтобы не удалить записи другого клиента.
* Действие простоя `stop` теряет память процессов. `hibernate` сохраняет снимок VM, но пробуждение зависит от записанного узла.
* Пробуждение по запросу для остановленной песочницы зависит от теплой локальной копии; клиент должен обработать повторяемую ошибку недоступности и явно выполнить возобновление.
* Изменение ресурсов прерывает рабочую нагрузку. Перед применением остановите прием запросов и убедитесь, что сервисы умеют перезапускаться.
* Неверное окно простоя, действие, режим хранилища или диапазон ресурсов возвращает HTTP `400`. Межаккаунтный доступ возвращает `404`.

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

* [Создание песочницы](/sandboxes/create-a-sandbox.md)
* [Жизненный цикл песочницы](/sandboxes/lifecycle.md)
* [Постоянные данные и хранилище](/sandboxes/persistence-and-storage.md)
* [Секреты](/secrets.md)
* [Справочник REST API](/api-reference/rest.md)
* [Наблюдаемость и диагностика](/sandboxes/observability-and-troubleshooting.md)
