# Шаблоны

Шаблон — переиспользуемая отправная файловая система для песочницы. У шаблона есть метаданные, ограничения ресурсов, пресеты и одна или несколько пронумерованных версий файловой системы. Шаблоны позволяют воспроизводить окружение, не собирая его заново в каждой новой песочнице.

Шаблон не является запущенной песочницей. При создании песочница получает собственный жизненный цикл и закрепляется за одной версией шаблона. Последующие изменения шаблона не переписывают существующую песочницу.

## Шаблон, версия, пресет и песочница[​](#template-version-preset-and-sandbox "Прямая ссылка на Шаблон, версия, пресет и песочница")

| Объект             | Чем владеет                                                                       | Что изменяется независимо                                                                        |
| ------------------ | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| **Шаблон**         | Имя, описание, README, теги, видимость, значения ресурсов по умолчанию и минимумы | Метаданные, версия по умолчанию, пресеты                                                         |
| **Версия шаблона** | Один пронумерованный снимок файловой системы и его состояние доступности          | Заметка и назначение версией по умолчанию; содержимое файловой системы не редактируется на месте |
| **Пресет**         | Ресурсы запуска и необязательные настройки подготовки для одного шаблона          | vCPU, RAM, окружение, интеграции, порты и сервисы                                                |
| **Песочница**      | Запускаемый экземпляр из одной конкретной версии шаблона                          | Файлы, процессы, ресурсы, настройки, жизненный цикл и удаление                                   |

Актуальный каталог находится на странице *Шаблоны* в продукте. Документация объясняет механику, но не поддерживает второй список доступных шаблонов.

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

```
                          ┌── default ready version ──┐
catalog template ─────────┤                           ├──► new sandbox
                          └── explicitly pinned vN ───┘       │
catalog preset ─────────────── launch settings ───────────────┘

running or stopped sandbox
          │
          └── Save as template ──► template + new default vN
                                             └── default preset
```

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

## Выбор из каталога[​](#choose-from-the-catalog "Прямая ссылка на Выбор из каталога")

Аутентифицированный каталог содержит:

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

Откройте шаблон и до создания песочницы проверьте его README, краткое описание, теги, минимальные ресурсы, пресеты и версии. Веб-каталог может открыть форму создания с пресетом по умолчанию или первым доступным пресетом. REST- и MCP-клиенты могут получить каталог и передать имя шаблона напрямую.

Скрытый шаблон отсутствует в обычных списках каталога. Владеющий аккаунт все еще может обратиться к нему по точному имени при создании через API; другие аккаунты не могут обнаружить или использовать его.

## Версии и воспроизводимость[​](#versions-and-reproducibility "Прямая ссылка на Версии и воспроизводимость")

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

При создании песочницы:

* не передавайте `template_version`, чтобы выбрать текущую готовую версию по умолчанию;
* передайте `template_version`, чтобы закрепить конкретную готовую версию;
* ожидайте отказа для отсутствующей или неготовой явно выбранной версии.

Состоянием версии может быть `ready`, `uploading`, `failed` или `deleting`. Экран управления также показывает заметки, размеры, связанные песочницы и зависящую от инсталляции доступность на отдельных узлах. Владельцы могут менять готовую версию по умолчанию и редактировать заметки; заметка не изменяет файловую систему.

Версию по умолчанию удалить нельзя. Другую версию также нельзя удалить, пока на нее ссылается хотя бы одна песочница в любом состоянии жизненного цикла. Удаление неиспользуемой версии выполняется асинхронно.

## Создание шаблона из песочницы[​](#create-a-template-from-a-sandbox "Прямая ссылка на Создание шаблона из песочницы")

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

Новое имя создает приватный шаблон и его первую версию. Для сохранения в существующий шаблон активного аккаунта нужно явно включить `overwrite`. Эта настройка добавляет следующую версию и делает ее версией по умолчанию, а не редактирует старый снимок файловой системы на месте.

Кому доступна сохраненная файловая система

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

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

Доступность после сохранения

Версию можно использовать на узле, где она была создана. Распространение на другие узлы зависит от конфигурации хранилища шаблонов в инсталляции и может продолжаться в фоне.

## Пресеты — это настройки запуска[​](#presets-are-launch-settings "Прямая ссылка на Пресеты — это настройки запуска")

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

* vCPU и RAM;
* значения окружения;
* MCP-серверы и навыки песочницы;
* учетные данные Git;
* публикуемые порты и сервисы;
* настройку подготовки `configure_claude`.

Пресеты не содержат состояние файловой системы и не создают новую версию шаблона. Один нескрытый пресет может быть отмечен как пресет по умолчанию для шаблона.

В веб-интерфейсе выбор пресета заполняет форму создания. В REST- и MCP-пути создания пресет шаблона по умолчанию предоставляет отсутствующие настройки подготовки. Явные значения клиента приоритетнее: окружение объединяется по ключам, а списочные настройки — MCP-серверы, навыки, учетные данные, порты и сервисы — подставляются только тогда, когда соответствующее поле отсутствует в запросе.

## Видимость, владение и блокировки[​](#visibility-ownership-and-locks "Прямая ссылка на Видимость, владение и блокировки")

Шаблоны и пресеты принадлежат активному личному аккаунту или организации. Обычное чтение возвращает собственные записи активного аккаунта и публичные записи. Изменять объект может владеющий аккаунт или администратор платформы.

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

Замороженный шаблон отклоняет существенные изменения шаблона, смену версии по умолчанию, удаление версии или всего шаблона и повторное сохранение под тем же именем до разморозки администратором. README и заметки версий остаются редактируемыми, поскольку не меняют поведение среды выполнения.

## Поведение при очистке[​](#cleanup-behavior "Прямая ссылка на Поведение при очистке")

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

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

## Точки входа[​](#entry-points "Прямая ссылка на Точки входа")

| Способ                                      | Для чего использовать                                                               |
| ------------------------------------------- | ----------------------------------------------------------------------------------- |
| Веб-интерфейс → *Шаблоны*                   | Просмотр каталога, создание песочницы и управление собственными шаблонами           |
| Действие песочницы → *Сохранить как шаблон* | Зафиксировать активную или остановленную песочницу как новую версию                 |
| REST `/v1/templates` и `/v1/presets`        | Чтение каталога и пользовательское управление шаблонами, версиями и пресетами       |
| MCP управления платформой                   | Получить шаблоны и версии, затем создать песочницу по имени и необязательной версии |

## Подробнее о шаблонах[​](#explore-templates "Прямая ссылка на Подробнее о шаблонах")

* [Выбор шаблона](/templates/choose-a-template) — метаданные каталога, требования, пресеты и версии.
* [Пресеты](/templates/presets) — переиспользуемая конфигурация запуска и приоритет значений.
* [Создание шаблона](/templates/create-a-template) — сохранение песочницы и последствия для источника.
* [Версии](/templates/versions) — версия по умолчанию, закрепление, доступность и удаление.
* [Видимость и совместный доступ](/templates/visibility-and-sharing) — приватные, публичные, скрытые и замороженные состояния.
* [Требования и лимиты](/templates/requirements-and-limits) — имена, ресурсы, хранилище и ограничения жизненного цикла.
* [Создание песочницы](/sandboxes/create-a-sandbox.md) — применить шаблон к новой песочнице.
* [Справочник REST API](/api-reference/rest.md) — точные схемы шаблона, пресета, версии и сохранения как шаблона.
