`layero deploy`

Упаковывает cwd и публикует его как новый деплой проекта. Git и GitHub не требуются — CLI заливает локальную директорию напрямую.

Базовое использование

cd my-site
npx layero@latest deploy

Что происходит:

CLI авто-детектит фреймворк (package.json, конфиги типа vite.config.ts/next.config.js) — заполняет framework_hint / build_cmd / output_dir если они ещё не заданы в .layero/project.json.
Обходит cwd, применяет правила игнорирования (см. ниже), пакует в tar.gz во временной директории и считает sha256 на лету.
Архив заливается в Yandex Object Storage по presigned URL.
Бэкенд создаёт деплой и запускает сборку.
CLI поллит логи деплоя (/deploys/{id}/logs) до статуса ready или failed, выводя их в терминал.
По окончании печатается ссылка — preview или production URL.

Первый layero deploy в новой папке создаст проект и запишет ./.layero/project.json. Последующие запуски используют тот же проект — никакого визарда в браузере, никакой ручной привязки.

Авто-детект фреймворка

CLI читает package.json и характерные конфиги:

Сигнал	Фреймворк	`build_cmd`	`output_dir`
`next` в deps / `next.config.*`	nextjs	`npm run build` (или `npx next build`)	`out`
`nuxt` в deps / `nuxt.config.*`	nuxt	`npm run generate` если есть, иначе `npm run build`	`.output/public`
`@sveltejs/kit` / `svelte.config.js`	sveltekit	`npm run build`	`build`
`gatsby` в deps	gatsby	`npm run build`	`public`
`astro` в deps / `astro.config.*`	astro	`npm run build`	`dist`
`@docusaurus/core` / `docusaurus.config.*`	docusaurus	`npm run build`	`build`
`vite` в deps / `vite.config.*`	vite	`npm run build`	`dist`
`react-scripts` в deps	cra	`npm run build`	`build`
`.html` в корне, нет `package.json`	static	`true` (no-op)	`.`

Если детект ошибся — отредактируйте .layero/project.json вручную или передайте --type явно.

Эти значения хранятся в .layero/project.json после первого деплоя. Они переживают повторные запуски и редактируются вручную.

Флаги

Флаг	Описание
`--prod`	Деплой приземляется в default-ветку проекта (то же что push в main). Если у проекта включён auto-promote — apex переключится на свежий билд автоматически.
`--promote`	После успешного билда сразу двигает `production_deploy_id` на этот деплой. Работает для любой ветки — удобно чтобы выкатить feature-ветку в production одной командой.
`--branch <name>`	Не работает для `deploy` — архивные загрузки всегда идут в псевдо-ветку `cli` (см. ниже). Флаг осмыслен только для `layero promote --branch`.
`--prebuilt [dir]`	Отправить готовую сборку вместо сборки на платформе. Без аргумента берётся первый существующий из `dist/`, `build/`, `public/`, `out/`, `_site/`. Правила `.gitignore` и `.layeroignore` при этом не применяются — см. врезку ниже.
`--type <preset>`	Оверрайд авто-детекта: `vite`, `next`, `astro`, `cra`, `sveltekit`, `nuxt`, `gatsby`, `docusaurus`, `static`.
`--name <name>`	Имя проекта. Только при первом деплое.
`--project <id_or_slug>`	Деплоить в конкретный проект, игнорируя `./.layero/project.json`. Удобно для CI.
`--org <slug>`	Создать проект в указанной Layero-организации (при первом деплое).
`--yes`, `-y`	Пропустить подтверждение `--prod` / `--promote` и интерактивные вопросы.
`--json`	JSON-lines на stdout (для AI-агентов и CI).
`--config`	Legacy alias текущего поведения (авто-детект + `.layero/project.json`).

Куда приземляется деплой

# CLI-проект (без подключённого репозитория): публикуется в apex АВТОМАТИЧЕСКИ.
# Прямые загрузки авто-промоутятся — отдельный --prod / promote не нужен.
npx layero@latest deploy
# → production-адрес проекта (живой публичный адрес; печатается в выводе)

# CI-режим: без подтверждения
npx layero@latest deploy --prod --yes

Для CLI-проекта (без репозитория) каждый layero deploy заменяет то, что отдаёт apex — это и есть публикация. Адрес работает сразу после первого успешного билда: прогрева CDN, который раньше занимал несколько минут, больше нет — пользовательские сайты идут напрямую на edge платформы.

Конкретный вид адреса зависит от того, в какой доменной зоне живёт проект (<project>.layero.app или, у проектов старше 26 июля 2026, <org>-<project>.layero.app) — см. Окружения, preview и production. Не собирайте адрес по шаблону: берите его из поля url события ready.

Чем --prod отличается от --promote (актуально для git-проектов; для прямых CLI-загрузок apex двигается и так):

--prod = «положи на default-ветку». Дальше за apex отвечает либо auto-promote (если включён в Settings), либо ваш ручной клик «Promote».
--promote = «после того как соберётся, переведи apex на этот деплой». Работает для любой ветки — короткий путь «hot-fix из feature-ветки → production».

--branch в layero deploy не работает

Флаг принимается и молча игнорируется: архивные загрузки бэкенд всегда кладёт в зарезервированное окружение cli — чтобы ручная загрузка не столкнулась с веткой подключённого репозитория (projects.py:2865). Проверено опытом: после layero deploy --branch=probe окружение probe не создаётся.

Что это значит на практике:

Проект без репозитория. cli у него и есть ветка по умолчанию, поэтому деплой авто-промоутится на апекс. Каждый layero deploy заменяет живой сайт, и способа загрузить непромоутящую версию из CLI нет.
Проект с подключённым репозиторием. cli — не дефолтная ветка, поэтому CLI-загрузка живёт на отдельном адресе <проект>-cli и апекс не двигает (пока не передан --prod).

Превью веток — это git-путь: пуш в ветку создаёт окружение через вебхук.

--prebuilt не смотрит в .gitignore

Флаг указывает на каталог готовой сборки, где правила исходного дерева бессмысленны, поэтому .gitignore и .layeroignore там не применяются. Это задумано — но у этого есть обратная сторона.

layero deploy --prebuilt . на корне проекта опубликует всё, что там лежит, кроме встроенного списка исключений, — включая черновики и заметки, которые вы спрятали через .gitignore. Проверено на живом деплое: файл из .gitignore после такой команды отдаётся с кодом 200.

Секреты при этом в безопасности: .env, .env.*, .git, node_modules и файлы правил исключены и на этом пути тоже (проверено, включая вложенные каталоги). Но каталог для --prebuilt всё равно стоит указывать явно.

Mixed-mode: GitHub + CLI на одном проекте

Один и тот же проект может одновременно принимать:

push в GitHub → автоматический деплой (webhook)
layero deploy → CLI-загрузка тарбола

GitHub-интеграция — необязательна. Первый деплой через CLI не требует ни git-репозитория, ни GitHub-аккаунта. Подключить GitHub можно потом, через дашборд, если захочется auto-deploy on push.

Mixed-mode удобен, когда:

GitHub-build долгий или нестабильный, и нужен быстрый локальный hot-fix: layero deploy --prod --yes поднимет ваш локальный код в production за секунды без коммита.
В CI после успешного теста хочется явно зафиксировать релиз: layero deploy --prod --yes после git push.

Артефакты в дашборде помечаются источником:

Бейдж	Что значит
`push`	Webhook от GitHub push
`cli`	Загружен через `layero deploy`
`manual`	Запущен через дашборд (Redeploy)

Пример CI-сборки:

LAYERO_TOKEN=$LAYERO_DEPLOY_TOKEN npx layero@latest deploy --prod --yes \
  --project alice-my-site

JSON-режим для агентов и CI

Любая команда CLI поддерживает --json (или LAYERO_JSON=1):

npx layero@latest deploy --json

Каждая строка stdout — JSON-объект с полем event:

{"event":"detected","framework":"vite","build_cmd":"npm run build","output_dir":"dist","confident":true}
{"event":"project_created","project_id":"...","slug":"my-site","organization":"alice"}
{"event":"packing","files":124,"bytes":2401234,"sha256":"..."}
{"event":"uploading"}
{"event":"deploy_started","deploy_id":"..."}
{"event":"build_log","line":"...","stream":"stdout"}
{"event":"ready","url":"https://my-site.layero.app/","dashboard_url":"https://app.layero.ru/projects/...","deploy_id":"..."}

url — живой публичный сайт (apex), открывать нужно именно его. dashboard_url — страница управления, НЕ сам сайт.

Ошибки приходят со стабильным code и next_action:

{"event":"error","code":"cli_deploys_disabled","next_action":"enable them in project settings","message":"CLI deploys are disabled on project \"my-site\""}

Не залогинены? layero deploy сам запустит device-flow (событие auth_required → клик по ссылке → poll), отдельный layero login не нужен.

В событии ready: url — живой публичный сайт. Для CLI-проекта это production-адрес (прямые загрузки авто-промоутятся); для деплоя в именованную ветку — preview-адрес ветки. Показывайте пользователю именно url — он работает сразу. dashboard_url — страница управления, не сам сайт. Про legacy-поля preview_url / edge_ready — JSON-events схема.

JSON-режим включается автоматически когда CLI запущен внутри Cursor / Claude Code / любого процесса с не-TTY stdout. Подробнее — Деплой из AI-агентов, полный список событий — JSON-events схема.

Правила игнорирования

CLI уважает:

.gitignore (как git)
.layeroignore (тот же синтаксис, можно расширять/исключать)
встроенный denylist:
```
node_modules
.git
dist
build
.next
.env*
.DS_Store
.gitignore
.layeroignore
```
Сами файлы правил исключены намеренно: на сайте им делать нечего, а перечисляют они ровно те имена, которые вы решили спрятать — опубликованный .gitignore подсказывает, что искать.

подсказка

Артефакты сборки (dist, build, .next) не нужно заливать — сборка запускается на стороне Layero после распаковки.

Лимиты

Максимальный размер архива — 200 MB.
Время layero deploy ограничено таймаутами на бэкенде:
Стадия Лимит
clone / unpack 15 мин
install 30 мин
build 15 мин
upload в S3 10 мин

Стадия	Лимит
clone / unpack	15 мин
install	30 мин
build	15 мин
upload в S3	10 мин

Если ваш билд не укладывается — напишите в поддержку, лимиты повышаются индивидуально.

Окружение сборки

Каждая сборка запускается в изолированной песочнице на выделенной builder-VM:

CPU / память: 2 vCPU, 4 GB RAM, swap до 4 GB, лимит процессов — 1024.
Диск: writable scratch (/mnt/scratch, ~40 GB на одну сборку), tmpfs /tmp 256 MB. Кэши npm/yarn/pnpm автоматически перенаправляются на scratch — большие бинарники (rolldown, swc, sharp) скачиваются без ENOSPC.
Сеть: разрешён исходящий HTTPS к npm-зеркалу, GitHub, реестрам пакетов (npm, yarn) и S3. Произвольные внешние эндпоинты с этапа сборки недоступны — это защищает чужие билды от случайного или вредоносного трафика. Если вашему билду нужен доступ к закрытому реестру или CDN, напишите в поддержку.
Изоляция: gVisor (runsc) + seccomp + drop-all capabilities + read-only rootfs. Сборки разных проектов не видят друг друга и не имеют доступа к инфраструктуре Layero.

Среда не персистентна между билдами: всё, что вы записали в /tmp или /mnt/scratch, исчезает после завершения. Артефакты в output_dir (dist по умолчанию) загружаются в объектное хранилище, откуда их и раздаёт edge платформы.

После деплоя

После ready:

Preview-URL ветки доступен сразу после успешной сборки и живёт, пока существует сама ветка.
Apex (production-адрес проекта) отдаёт этот деплой, если он стал production: для CLI-проекта (без репозитория) это происходит автоматически на каждом layero deploy; для git-проекта — через auto-promote default-ветки или --promote. --branch на это не влияет — см. врезку выше.

См. Окружения, preview и production для полной картины.

Postinstall-баннер

После npm install -g layero или npm install -D layero (без --silent) CLI пишет краткий quick-start в /dev/tty. В CI-окружениях баннер подавляется автоматически (CI=1). Чтобы выключить вручную:

LAYERO_SKIP_POSTINSTALL=1 npm install -D layero

Базовое использование​

Авто-детект фреймворка​

Флаги​

Куда приземляется деплой​

Mixed-mode: GitHub + CLI на одном проекте​

JSON-режим для агентов и CI​

Правила игнорирования​

Лимиты​

Окружение сборки​

После деплоя​

Postinstall-баннер​