Перейти к содержимому

Self-Hosting

Запустите Moira на своей машине через Docker Compose. Основной путь скачивает готовый образ из реестра — клонировать исходники и собирать локально не нужно.

Требования

  • Docker с плагином Compose (docker compose)
  • Публичные docker-compose.yml, .env.example и config/traefik-self-host.yml; для обычного пути не нужны сборка исходников, private-репозиторий, CLI SQLite на хосте или отдельный upgrade-скрипт

Быстрый старт

Скачайте актуальные публичные self-host файлы:

Terminal window
MOIRA_FILES=https://raw.githubusercontent.com/moira-mcp/moira/master
curl -fLO "$MOIRA_FILES/docker-compose.yml"
curl -fLo .env.example "$MOIRA_FILES/.env.example"
mkdir -p config
curl -fLo config/traefik-self-host.yml "$MOIRA_FILES/config/traefik-self-host.yml"
  1. Создайте конфиг

    Terminal window
    cp .env.example .env

    Для запуска на localhost значения по умолчанию работают без изменений.

  2. Запустите сервисы

    Terminal window
    docker compose up -d

    Compose запускает приложение и статический Traefik ingress на одном публичном порту. Ingress не получает Docker socket. Сохраните его конфигурацию рядом с Compose.

  3. Откройте веб-интерфейс

    http://localhost:8080

    Ваш экземпляр также раздаёт эту документацию по адресу http://localhost:8080/docs/ (и /ru/docs/), а MCP-эндпоинт — по http://localhost:8080/mcp.

При первом запуске Moira генерирует недостающие секреты и одноразовый пароль администратора.

Конфигурация

DEPLOYMENT_MODE=self-host (по умолчанию) — установка для приватной команды с открытой регистрацией и подтверждением администратором. Новый пользователь может посмотреть статус подтверждения и выйти, но до подтверждения не получает доступ к workflow, API-токенам, OAuth и MCP. Верификация email остаётся отдельной проверкой и в self-host не обязательна. Недостающие секреты генерируются при первом запуске.

Администратору self-host остаётся доступна страница Пользователи для подтверждения, блокировки и восстановления учётных записей. В строках также показаны записанная активность, последний принятый шаг, если он записан, число запусков и наиболее используемые флоу. Эти сведения управления не зависят от периодов и исключений аналитики; отсутствие записи об активности или шаге обозначается как неизвестное. Сквозное администрирование чужих workflow, исполнений и артефактов, облачная аналитика, операционная панель и инструменты намеренной проверки мониторинга отключены на сервере и не показываются в навигации. Это возможности режима установки, а не только скрытые элементы интерфейса. Политика SaaS включает их через тот же resolver, который используют API и веб-интерфейс. Панель self-host по-прежнему показывает состояние базы данных, определений настроек и сверки управляемых workflow, но не запрашивает и не отображает общие показатели workflow и исполнений всей установки.

Подтверждение новых пользователей

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

Эквивалентная операция API — POST /api/admin/users/:id/approve, а GET /api/admin/users возвращает время подтверждения. Операция идемпотентна: повтор запроса после неопределённого ответа не меняет первоначальное время и не создаёт второй переход. Миграция помечает существующих пользователей подтверждёнными, а начальный администратор всегда создаётся подтверждённым. Блокировка и верификация email независимы от подтверждения: заблокированная учётная запись не получает доступ даже после подтверждения.

Настройка почты и восстановление без неё

По умолчанию доставка писем отключена. Чтобы включить письма для сброса пароля и верификации, настройте стандартный SMTP-сервер в .env и перезапустите контейнер:

Terminal window
EMAIL_PROVIDER=smtp
EMAIL_FROM=moira@example.com
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_REQUIRE_TLS=true
SMTP_USER=your-smtp-user
SMTP_PASSWORD=your-smtp-password

SMTP-аутентификация необязательна, но SMTP_USER и SMTP_PASSWORD задаются только вместе. Для неявного TLS (обычно порт 465) используйте SMTP_SECURE=true; в остальных случаях SMTP_REQUIRE_TLS=true требует STARTTLS. Brevo по-прежнему доступен с EMAIL_PROVIDER=brevo, BREVO_API_KEY и EMAIL_FROM. При неполной или некорректной конфигурации запуск прерывается. Режим SaaS также не запускается без реального провайдера.

С EMAIL_PROVIDER=none (значение по умолчанию) Moira запускается, а веб-интерфейс честно сообщает, что восстановление пароля и почтовые действия недоступны. Администратор может открыть карточку обычного пользователя, выбрать Установить временный пароль и передать его по отдельному защищённому каналу. Действие отзывает все сессии пользователя, API-токены, OAuth-учётные данные и согласия. Пользователь входит с временным паролем и обязан сразу его заменить. Для учётных записей администраторов используйте описанную ниже CLI-процедуру.

EMAIL_PROVIDER=test предназначен только для записи писем в лог в автоматических тестах. Он не означает настроенную доставку и не сообщает о записанном письме как об отправленном.

Восстановление доступа администратора

В каталоге с docker-compose.yml задайте новый пароль так, чтобы он не попал в историю shell:

Terminal window
read -s ADMIN_PASSWORD
export ADMIN_PASSWORD
docker compose exec -e ADMIN_PASSWORD moira npx tsx scripts/create-admin-user.ts
unset ADMIN_PASSWORD

ADMIN_PASSWORD обязателен. Значения ADMIN_EMAIL и ADMIN_ID по умолчанию — admin@moira.local и system-admin, а DB_PATH — ./data/moira.db. Для переопределения добавьте к docker compose exec аргументы -e ADMIN_EMAIL, -e ADMIN_ID или -e DB_PATH. Команда создаёт или восстанавливает администратора, помечает email и учётную запись подтверждёнными, снимает блокировку и заменяет credential. Пароль в вывод не попадает.

Откат на версию без подтверждения учётных записей

Старый образ не учитывает approvedAt. Перед закреплением такого образа остановите внешний трафик, создайте резервную копию базы и выполните преобразование на текущем образе:

Terminal window
docker compose exec moira npm run prepare:account-approval-downgrade -- \
--confirm-block-pending-users

Без аргумента подтверждения команда отказывается работать. В одной транзакции она блокирует каждого ожидающего пользователя через старое поле blocked и отзывает его сессии, API-токены, OAuth-токены и OAuth-согласия. Проверьте выведенные счётчики до остановки текущего контейнера. Не выполняйте откат раньше преобразования: старый образ не умеет его делать. При возврате на версию с подтверждением сначала проверьте каждую преобразованную учётную запись, а затем подтвердите и явно разблокируйте её.

Переменные, зависящие от хоста

Эти три должны указывать на ваш хост и иметь согласованные порты. Значения по умолчанию нацелены на localhost:8080, поэтому для запуска на localhost правки не нужны.

ПеременнаяПо умолчаниюНазначение
MOIRA_HOSTlocalhost:8080Публичный хост (протокол определяется автоматически)
MOIRA_PORT8080Порт хоста, проброшенный в контейнер
STATIC_ARTIFACTS_DOMAINstatic.localhost:8080Домен для размещаемых HTML-артефактов

Для реального хоста или другого порта меняйте все три вместе:

Terminal window
MOIRA_HOST=moira.example.com
MOIRA_PORT=8080
STATIC_ARTIFACTS_DOMAIN=static.example.com

STATIC_ARTIFACTS_DOMAIN обязателен — при пустом значении запуск прерывается.

За обратным прокси

Лимиты запросов, исключение RATE_LIMIT_WHITELIST, записи аудита и адреса сессий Moira привязывает к адресу клиента. Этот адрес она берёт из X-Forwarded-For только через прокси, перечисленные в TRUST_PROXY; записи, которые клиент дописал сам, не используются никогда.

  • Поставляемый Compose задаёт TRUST_PROXY=2: обычные запросы проходят Traefik и nginx, а потоки workspace — прямо из Traefik в backend. Traefik отбрасывает недоверенные forwarding-заголовки клиента.
  • При дополнительном обратном прокси настройте замену недоверенных forwarding-заголовков и явно задайте доверенные адреса/подсети всей топологии. У обычного и workspace маршрутов разное число переходов; проверяйте оба, прежде чем увеличивать общий hop count.

Если внешний прокси передаёт адреса клиентов, добавьте --entrypoints.web.forwardedheaders.trustedips=<его IP или CIDR> в команду поставляемого ingress. Доверяйте только фактическим адресам этого прокси; не включайте insecure-доверие заголовкам.

Terminal window
TRUST_PROXY=loopback,172.18.0.0/16 # пример: только фактическая сеть ваших прокси и nginx

Без этой настройки все клиенты за вашим прокси получают его адрес и один общий лимит запросов. TRUST_PROXY=true не принимается, а при неверном значении запуск прерывается с ошибкой, в которой перечислены допустимые формы.

Публичный путь /api/workspaces/ требует HTTP/1.1 Upgrade прямо в backend приложения на порту 3001. Поставляемый ingress предоставляет этот маршрут без ограничения простоя или длительности установленного потока. Внешний ingress должен сохранять TLS и тот же origin приложения. Общий маршрут через nginx 80 или один frontend-порт отдельного контейнера приложения не являются поддерживаемым путём workspace-потоков. Глобальный default приложения остаётся loopback; Compose переопределяет его только для своей топологии.

Автогенерируемые секреты

В режиме self-host они генерируются при первом запуске и сохраняются в <data-dir>/.secrets.env. Оставьте их пустыми в .env:

ПеременнаяСгенерированное значение
BETTER_AUTH_SECRETКлюч шифрования сессий
TELEGRAM_ENCRYPTION_KEYКлюч шифрования учётных данных Telegram
ADMIN_PASSWORDПароль администратора, выводится в логи один раз

Данные для входа администратора выводятся в логи контейнера один раз при первом запуске:

Terminal window
docker compose logs | grep -A3 "ADMIN LOGIN"

Войдите с ADMIN_EMAIL (по умолчанию admin@moira.local) и выведенным паролем.

Подключение локальных кодспейсов

Настройки → Разработка → Локальные компьютеры связывают компьютер с Moira Local и этим аккаунтом. Local и GitHub используют отдельные инструменты workspace, команд, файлов и процессов с возвращаемыми ссылками на окружения и исходные операции. Сопряжение, чтение публичных репозиториев и базовая локальная работа не требуют GitHub App и серверного хранилища credentials. Доступ сопряжённого устройства к приватным репозиториям, push и операции PR требуют серверного OAuth-подключения GitHub App и настроенного хранилища. Локальная работа требует текущих прав владельца компьютера и включённого разрешения до явного отключения; облачных операционных контролей и общей квоты ресурсов у неё нет. Переключатель CODESPACE_CODESPACES_ENABLED управляет GitHub, а не Local. Контроллер инициирует исходящее HTTPS-соединение и не открывает публичный порт.

Сопряжение и run не требуют init, Local SDK или дискового образа. Для GitHub и файлов коммуникации можно сначала выполнить показанный браузером enroll, подтвердить устройство и выполнить npm run local -- install, затем npm run local -- run. Установка размещает полный неизменяемый релиз и регистрирует запуск при входе в macOS. run запускает постоянную службу владельца или подключается к ней и возвращает управление; закрытие клиента не останавливает VM. Физическая Local-возможность настраивается отдельно.

Нужны Node.js 24, macOS на Apple silicon и подписанный Docker Sandboxes sbx 0.46.0 из официальных release artifacts. См. требования установки Docker. Физическое исполнение Local VM на Linux отклоняется. Соберите приватный пакет companion из checkout Moira при доступном C compiler платформы контроллера; опубликованного глобального npm installer нет:

Terminal window
npm ci
npm run local:build
npm run local -- init --sbx /absolute/path/to/Sbx.app/Contents/MacOS/sbx --label My-computer
npm run local -- login
npm run local -- setup
npm run local -- approve OWNER/REPO
npm run local -- enable
npm run local -- doctor

init создаёт приватное состояние и дисковый образ с ограниченной ёмкостью; работа выключена. Образ монтируется по короткому пути собственного устройства, чтобы сокеты SDK помещались в системный предел. --state PATH выбирает другой каталог состояния; повторяйте его в каждой команде. --storage-gib, --cpus и --memory-gib задают выделенные ресурсы при инициализации. setup требует пустой выделенный профиль SDK. doctor проверяет предпосылки при включённом разрешении на работу; liveVmIsolationVerified: false не является результатом проверки изоляции настоящей microVM.

Companion хранит Docker sign-in в отдельном зашифрованном хранилище SDK и не изменяет выбор личного Docker-профиля или Keychain. Если служба владельца работает, перед локальным входом, setup или восстановлением credentials используйте описанную ниже явную приостановку обслуживания. Замена хранилища дополнительно требует выключенной работы и npm run local -- login --new-store. Это явное действие проверяет остановку собственных процессов, создаёт отдельное хранилище и сохраняет существующие credentials. Ошибка не вызывает автоматическую ротацию или импорт личных credentials. Это машинное хранилище доверяет аккаунту хоста: сгенерированный пароль хранится в локальном файле, доступном только владельцу; блокировка при sleep/по интервалу выключена только для хранилища SDK, а не личной Keychain. Служба macOS запускается в собственной сессии безопасности без графического интерфейса. Ошибка разблокировки остаётся отказом credentials: служба не сбрасывает хранилище и не запускает повторный вход через браузер автоматически.

Права на репозиторий выдаются на компьютере. approve OWNER/REPO разрешает чтение. Добавляйте --private, --push и --delete только для соответствующих прав. Ручные токены репозитория не принимаются. Сопряжённый приватный доступ и push используют одобренный grant GitHub App через доверенный брокер производных credentials владельца, без перехода на токен хоста. Команда enable разрешает работу до явной команды disable; срок и продление не требуются. Браузер может менять эти настройки только после явного разрешения веб-управления на компьютере, описанного ниже.

В Локальных компьютерах выберите Подключить компьютер. Скопируйте показанную команду и токен сопряжения отдельно. В checkout выполните её через npm run local -- enroll --server <показанный HTTPS URL приложения> --pairing-id <показанный ID>. Введите токен в stdin и завершите ввод; не дописывайте его в команду. URL сервера включает настроенный префикс приложения и не содержит credentials, query или fragment. Обновите браузер, проверьте identity ожидающего компьютера, затем подтвердите подключение. Действующие права читаются у доступного локального контроллера после подключения.

Сервер и владелец требуют согласованных управляющих контрактов. service-status отдельно показывает работающий релиз и подготовленное обновление. Обычная установка сохраняет действующего владельца, broker/tunnel и работающие VM; несовместимый клиент сообщает о необходимости обслуживания. Перед заменой физического владельца сохраните серверную базу, полный приватный каталог Local, backing storage SDK с дисками VM и согласованные исполняемые бандлы. Соберите и подготовьте релиз:

Terminal window
npm run local:build
npm run local -- install
npm run local -- service-status
npm run local -- maintenance --confirm

До отправки maintenance печатает ID исходного запроса. При потерянном ответе используйте collect ORIGINAL_REQUEST_ID, а не новый запрос обслуживания. Замена ждёт подтверждённой физической остановки, сохраняет identity VM, диски и намерение запуска, затем восстанавливает те же известные окружения без повтора команд. Операция прерывает работу и отдельно сообщает о недоступных окружениях. Неподтверждённая остановка блокирует замену. Пересборка checkout или подготовка пакета сами по себе не заменяют работающего владельца.

Прямое локальное администрирование, которому нужна блокировка владельца, использует явную приостановку. Читайте результат по напечатанному ID до фазы paused, выполните нужное действие и продолжите обслуживание по тому же ID:

Terminal window
npm run local -- maintenance --pause --confirm
npm run local -- collect ORIGINAL_REQUEST_ID
# Только после paused выполните нужный локальный вход, setup или одобрение.
npm run local -- maintenance --resume --request-id ORIGINAL_REQUEST_ID --confirm

Повторяйте --state PATH во всех командах, если он задан. Приостановка прерывает физическую работу, сохраняя исходное намерение; она не сбрасывает credentials и не разрешает второго владельца. При неопределённой приостановке сохраните исходные записи и устраните причину до продолжения. Перезагрузка компьютера также прерывает исполнение: после входа служба восстанавливает сохранённое намерение запуска известных VM при доступных runtime и credentials, без повтора команд. Она не запускается до входа и не обещает непрерывность гостевых процессов при перезагрузке.

Архивные облачные Local policy/control, relay, grants и операционные записи сохраняются в неизменяемых архивах; они не являются действующими правами или очередью работы. Владелец импортирует только проверенные существующие native bindings и сохраняет неизвестные исходы. Неподдерживаемое приватное состояние владельца остаётся отказом: сохраните резервную копию, identity, журналы и диски вместо правки облачной policy для обхода отказа. Откат восстанавливает обе копии и согласованные бандлы; сброс SDK или новое сопряжение не требуются.

Сервер хранит только identity локального ресурса, репозитория и соединения, одобренную привязку устройства/профиля и подтверждение окончательного удаления. Машина, текущее состояние и lifecycle-поколение приходят от доступного владельца. Полные строки ресурсов и привязок остаются в неизменяемых архивах с сохранением публичных ID, значения отзыва и существующие гостевые credentials. VM и диски не пересоздаются. Отзыв устройства не доказывает удаления диска; неизвестные или не удалённые Local ресурсы сохраняют ожидание при удалении аккаунта. Для отката восстановите согласованную базу до миграции и соответствующую копию состояния владельца; не восстанавливайте выполнение из архивных запросов.

После подтверждённого сопряжения разрешите локальное веб-управление:

Terminal window
npm run local -- web-control --confirm

Используйте тот же --state PATH, что при настройке. При первом одобрении неуказанные пределы ресурсов берутся из текущих локальных значений. Повторите web-control --confirm на этом компьютере, чтобы пересмотреть одобрение: неуказанные параметры тогда сохраняют ранее одобренные пределы. Изменённый максимум задаётся через --cpus, --memory-gib, --storage-gib или --docker-gib. Сервер, аккаунт, компьютер и соединение должны оставаться прежними. Существующие права, состояние применения и восстановления сохраняются; запросы браузера или агента не могут повышать эти максимумы. Само одобрение не включает работу и не меняет фактический размер диска.

Например, чтобы разрешить общее хранилище 50 ГиБ при работающем владельце, выполните описанную выше приостановку обслуживания и дождитесь paused. Затем выполните:

Terminal window
npm run local -- web-control --confirm --storage-gib 50
npm run local -- maintenance --resume --request-id ORIGINAL_REQUEST_ID --confirm

Повторяйте тот же --state PATH в обеих командах, если он задан. Не используйте disable только ради изменения максимума: эта команда также выключает и останавливает собственную работу. Обновите Локальные компьютеры, задайте хранилище 50 в существующем редакторе этого компьютера и нажмите Запросить изменение настроек. Companion применяет запрошенный размер через существующий resize с остановкой собственных процессов. Дождитесь применённой редакции и фактического размера: ожидание не означает завершённый resize. Локальное подтверждение сохраняет существующий диск и кодспейсы, а не создаёт заменяющие VM. Если владелец ещё не установлен или не запущен, после локального одобрения запустите его или подключитесь:

Terminal window
npm run local -- run

В Локальных компьютерах редактируются имя, включение работы, CPU/RAM, ограниченный диск и ёмкость гостевого Docker, права репозиториев, автор коммитов. Включённое разрешение действует до явного отключения. У команд и файловых потоков нет квот Moira на параллельность, байты, хранение вывода или runtime. Явно запрошенный срок команды и настоящая ёмкость машины/диска остаются действующими границами. Запросить изменение настроек отправляет запрос с исходным ID доступному владельцу, а не выдаёт действующие права. При недоступном компьютере сохранение отклоняется и черновик остаётся в редакторе; восстановите связь и обновите состояние перед явным сохранением. Применённая и отклонённая редакции показывают результат владельца. Перед работой проверьте действующие разрешения над редактором. Ошибки сохраняют черновик; обновления меняют нетронутые поля, сохраняя независимые правки. Управляющее соединение может принимать настройки, когда работа выключена, но гостевая работа остаётся выключенной до применения включения. Изменения названия, прав, автора Git, делегирования и настроек новых VM применяются без остановки, если включение и общее хранилище не меняются; они не останавливают посторонние VM. Настройки CLI и браузера используют одну защищённую ревизию. Автор Git меняется в policy; подготовка workspace применяет это значение к локальной конфигурации репозитория. Само сохранение настройки не перезаписывает конфигурацию уже работающего checkout. При потере ответа читайте исходный запрос настроек, не отправляя его заново. Исторический результат остаётся исходным; текущие права обновляйте отдельным чтением. CPU/RAM и гостевой Docker задают профиль новых сред; существующие VM сохраняют принятый профиль. Ёмкость хранилища задаёт общий дисковый образ SDK на компьютере, а не отдельный диск такого размера для каждого кодспейса. Изменение ограниченного диска требует остановки собственных процессов и проверенного resize; отказ не разрешает дальнейшую работу и не удаляет данные. Для приватных репозиториев, push и создания PR через Moira подключите GitHub и предоставьте App доступ к репозиторию. Эти операции также требуют соответствующих прав репозитория устройства; чтение метаданных PR использует право чтения репозитория. Исходная OAuth/refresh authorization остаётся на сервере; доверенный брокер получает только производный scoped токен. Укажите автора коммитов или оставьте оба поля пустыми для проверенной GitHub identity, когда она доступна; Git-конфигурация компьютера не копируется.

После локального одобрения web control владелец может здесь включить управление репозиториями для агента. По умолчанию оно выключено; разрешение привязано к проверенному личному GitHub-аккаунту, отдельным правам на существующие/новые приватные репозитории и push. Квоты количества репозиториев или фиксированного профиля технологий нет. Разрешение действует только после подтверждённого применения владельцем. codespace({ action: "targets", provider: "local-sandboxes" }) возвращает цели Local и наблюдённую доступность контроллеров без чтения GitHub installations. codespace({ action: "targets", provider: "github-codespaces" }) возвращает цели GitHub, зарегистрированные контроллеры и подходящие личные installation-ссылки. Предупреждения о GitHub сохраняют зарегистрированные варианты; регистрация не подтверждает доступность маршрута. Её проверяет фактическая отправка выбранному владельцу без подмены контроллера. codespace (repository_admit) принимает возвращённую ссылку контроллера и числовой GitHub ID существующего приватного репозитория. Доступ появляется только после подтверждённого применения владельцем; агент не расширяет consent. Репозиторий должен быть доступен App. Для нового пустого приватного репозитория примените new-private consent и вызовите codespace (repository_create) с возвращёнными ссылками контроллера и installation и именем репозитория. Поддерживается подключённый личный аккаунт. Пригодная цель возвращается после применения доступа.

Сохраните возвращённую operation. codespace({ action: "collect", reference }) только читает исходный результат. После исправления permissions, installation access или локального допуска явно продолжите именно исходное создание через codespace({ action: "resume", reference }): инструмент использует сохранённые входные данные и не создаёт другой репозиторий. Он не продолжает команды или произвольные операции. Неизвестный исход проверяется по сохранённому marker; отсутствие наблюдения или чужой same-name репозиторий не разрешают повторный create. Сохраняйте recovery marker в description до разрешения неизвестного исхода; это не credential.

Владелец должен одобрить Repository creation: write либо Administration: write для create API и GitHub App installation repository access: write для selected installation. Одобренный push требует Contents write. После одобрения используйте Обновить права GitHub; Исходные OAuth и refresh credentials остаются на сервере. Доверенный брокер владельца получает только производный токен для одобренного репозитория и действия. Он напрямую выполняет HTTPS Git/PR и отзывает токен после закрытия внешнего соединения; облачная Moira не проксирует Git-байты и не выполняет PR-запросы. Токены не становятся проектными файлами, аргументами, переменными окружения или результатами инструментов. Доверие к одному UID не означает изоляцию брокера средствами ОС.

Используйте обычные git fetch/git push. codespace_git (create) принимает возвращённую ссылку workspace, head, base, title и необязательные body/draft и возвращает исходную operation. После неопределённого ответа используйте codespace_git (collect), а не повтор создания. codespace_git (read) читает PR или находит его по head/base. Гостевой CLI предлагает pr-create, get, pr-find и pr-get; идентичность запроса создаёт адаптер. При неопределённом сохранении или отзыве scoped credential сохраните отдельную security identity: moira-local status --json и moira-local collect ORIGINAL_SECURITY_REQUEST_ID читают исходный привилегированный запрос без выпуска токена. Чтение не отменяет живую передачу и не разрешает автоматический перевыпуск при отсутствии результата.

У каждого кодспейса своя VM; один репозиторий может иметь несколько кодспейсов. Локальные VM и операции не занимают облачные слоты Codespaces и не ограничиваются облачным машинным профилем. Один и тот же гостевой workspace service владеет командами, файлами, сессиями и сохранённым выводом обоих провайдеров. codespace_terminal (run) и codespace_terminal (run_native) принимают команду и возвращённую ссылку workspace; codespace_edit (create), codespace_edit (replace) и codespace_edit (patch) работают с путём, текстом и ожидаемым содержимым или возвращённой файловой ссылкой. UUID, числовые поколения, хеши и байтовые правки не являются обычными входами агента. Сохраните возвращённые ссылки operation и process. codespace_terminal (collect) читает исходный результат, codespace_terminal (output) — вывод, codespace_terminal (stop) запрашивает отмену. Незавершённая отмена не доказывает физическую остановку. После потери первого ответа используйте codespace_terminal (find) у выбранного владельца и явно выберите исходную операцию из кандидатов. Даже один кандидат не выбирается автоматически; отсутствие результата не доказывает отсутствие эффекта. Два намеренно одинаковых вызова — разные намерения, а не автоматическая дедупликация по тексту команды.

Гость хранит результаты и полные stdout/stderr на своём диске. Идентичность операции, digest и метаданные сравнения входа сохраняются, даже когда владелец удаляет проверенную временную копию нативного файла/stdin после соответствующего конечного результата и подтверждённого завершения чтения. Живая, неизвестная или конфликтующая работа сохраняет этот ввод. Чтение результата не получает источник повторно и не исполняет операцию заново. Облако передаёт живые авторизованные запросы без очереди команд или отдельной серверной копии их результатов. Потеря облачного соединения не отменяет команду; остановка провайдера может её прервать. Сохранённый конечный результат доступен, пока существуют данные workspace и действуют права. Команды и чтения независимы; фиксация и восстановление файлов используют транзакционную блокировку и проверки ожидаемого содержимого. timeout_seconds останавливает команду только при явном указании.

codespace_upload передаёт нативное вложение в выбранный путь. codespace_download публикует текущий файл как неизменяемую ссылку владельца и file.reference_id; имя и MIME выводятся, если не заданы. Предварительный stat не требуется. Публикация читается до своего срока при действующих правах; правка источника не меняет опубликованные байты. Необязательный max_bytes ограничивает выбранное скачивание или предпросмотр, а не объём работы workspace. communication (deliver) доставляет нативный источник, а communication (deliver_publication) — существующую публикацию. Необязательный channel выбирает настроенный канал, но не адресата. Доставка не расходует публикацию и не продлевает её срок. Возвращённая operation читается через communication (collect) без повторной загрузки, рендеринга или отправки. Результат workflow-уведомления с вложением также содержит operation; внутренняя identity execution/visit не нужна для чтения.

Фиксированный bootstrap провайдера устанавливает сервис и CLI ~/.local/bin/moira-workspace в существующее окружение без пересоздания диска. CLI обращается к тому же приватному Unix socket; в разрешённом работающем workspace он доступен и без облачного соединения. Собственные проверенные Node.js 24.21.0 и ripgrep 15.2.0 не зависят от версии Node или PATH проекта. Runtimes проекта устанавливаются самим проектом.

Terminal window
~/.local/bin/moira-workspace --help
~/.local/bin/moira-workspace exec -- pwd
~/.local/bin/moira-workspace stat package.json
~/.local/bin/moira-workspace search . TODO

Сохраните возвращённые ссылки и используйте get OPERATION_REF и output PROCESS_REF --stream stdout. Чтение не повторяет действие. Команды read, create, replace, upload, download и patch сохраняют те же проверки репозитория. Диагностика гостевого daemon ротируется отдельно в ~/.local/state/moira/workspace-service/daemon.log, daemon.log.1 и daemon.log.2, каждый ограничен 1 МиБ. Ротация не обрезает stdout/stderr команд; их полные потоки читаются по возвращённой ссылке процесса через output или codespace_terminal (output). Публичный образ — ghcr.io/moira-mcp/moira-workspace-service, необязательная Dev Container Feature — ghcr.io/moira-mcp/features/workspace-service. Выберите опубликованный release tag. Образ содержит runtime; Feature добавляет тот же payload в собственный Linux Dev Container проекта. Оба поддерживают glibc x64/arm64 и репозиторий, принадлежащий пользователю сервиса, включая явно выбранного root. Feature при пересборке контейнера необязательна: фиксированный bootstrap Moira обновляет существующее окружение без такой пересборки.

Чтобы добавить Feature в .devcontainer/devcontainer.json проекта, объедините эту запись с существующим объектом features и замените RELEASE_TAG доступным опубликованным тегом:

{
"features": {
"ghcr.io/moira-mcp/features/workspace-service:RELEASE_TAG": {}
}
}

Другой вариант — образ Dev Container ghcr.io/moira-mcp/moira-workspace-service:RELEASE_TAG с overrideCommand: true, чтобы контейнер мог запуститься до подготовки сервиса сопряжённым bootstrap. Эти файлы устанавливают runtime, но не предоставляют облачные права или доступ к репозиторию.

Публичные реестры пакетов и DNS-адреса доступны через одобренный broker. Квоты числа сокетов или длительности передачи нет; остаются streaming backpressure, проверка публичности адресов, текущее разрешение работы и отзыв прав. Host/LAN/служебные адреса запрещены. Совместимость браузера зависит от гостевых пакетов проекта. codespace_read (preview) читает текущий PNG/JPEG репозитория и проверяет контейнер перед возвращением нативного изображения; осмотрите его перед принятием как визуального свидетельства. Необязательный max_bytes задаёт выбранный предел всего изображения. Общих потолков байтов, сторон или числа пикселей нет. Проверка PNG/JPEG контролирует структуру, а не декодирует все пиксели. codespace_download публикует полный исходный файл. См. справочник инструментов.

В Настройки → Разработка → Локальные компьютеры откройте кодспейсы подключённого компьютера и выберите одобренный репозиторий для создания VM либо получите цель через codespace({ action: "targets", provider: "local-sandboxes" }). Один репозиторий на разных компьютерах — разные варианты выбора. codespace({ action: "list", provider: "local-sandboxes" }) и codespace (observe) возвращают ссылки сред для явных lifecycle-решений. Последующая работа использует возвращённую ссылку workspace. GitHub остаётся независимым. Отзыв устройства в браузере запрещает новую серверную работу, но не доказывает физическую остановку недоступного компьютера.

codespace (create) принимает цель и ветку; codespace (lifecycle) — возвращённую ссылку workspace и действие start/stop/resume_setup. codespace (delete) адресует ту же наблюдённую среду. Адаптер сохраняет исходные предусловия: конфликт требует нового наблюдения и явного решения, а не автоматического повтора с обновлённым поколением. Сохранённая operation читается через codespace (collect); после потери первого ответа используйте codespace (find) у выбранного контроллера. Ожидающие pending_operations позволяют продолжить чтение после перезагрузки. absent, недоступность и новые метаданные не разрешают повтор эффекта.

Если владелец не предоставил текущее наблюдение, список сохраняет собственную недоступную идентичность с безопасной ошибкой, без выдуманной машины, состояния или поколения. Она не скрывает исправных соседей. Неопределённое создание остаётся исходной операцией; даже завершённая приватная запись с неопределённым физическим исходом публично остаётся unconfirmed. Поиск показывает безопасные метаданные и ссылки, а полный исходный результат требует явного чтения. Подтверждённый отказ остаётся completed с outcome.ok:false; поиск и чтение одинаково отличают его от неопределённого исхода.

В карточке каждого компьютера находятся его форма создания, кодспейсы и свёрнутые настройки. Компьютеры с одинаковым названием не смешиваются; у одного репозитория может быть несколько отдельных VM. Общая ёмкость хранилища показана у компьютера, CPU и RAM — у каждой VM. GitHub Codespaces находится в отдельном подразделе. Обновление и ошибки действий принадлежат соответствующей секции или кодспейсу. Локальные карточки показывают время последнего проверенного наблюдения либо его отсутствие и локализованную причину отказа. Проверить состояние снова читает результат исходной lifecycle-операции, если её ID известен, либо только обновляет наблюдение. Она не повторяет запуск, остановку или удаление. Новое явное действие использует возвращённое наблюдение workspace без изменений. created не подтверждает остановку: независимый native owner должен проверить точный runtime и завершение его worker. Недоступное наблюдение сохраняет последнее проверенное состояние и не превращается в успешную остановку.

Удалить доступно при ожидающем создании, очистке и неопределённом локальном состоянии, с явным подтверждением и зафиксированной ссылкой workspace. Действие адресует ту же собственную VM и ждёт подтверждённого удаления; отказ наблюдения не позволяет убрать карточку как отсутствующую VM. Ошибка одной карточки не мешает обновлению и работе исправных соседних кодспейсов.

Для ручного удаления нужны активный сопряжённый компьютер с локальным одобрением веб-управления и работающий доступный companion. Оно доступно при запрете удаления агенту или выключенной работе. Подтверждение разрешает только адресное наблюдение и удаление; права репозитория не меняются и работа не включается. Удаление через MCP по-прежнему требует права агента на удаление и включённого разрешения работы.

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

Физический запуск VM отличается от готовности гостя: команды доступны только после завершения его подготовки. Для Local CODESPACE_LOCAL_SETUP_INCOMPLETE означает незавершённую подготовку, даже если VM подтверждённо остановлена. Исправьте указанную предпосылку, затем выберите Продолжить подготовку или codespace({ action: "lifecycle", workspace, operation: "resume_setup" }) с возвращённой ссылкой workspace. Это продолжает подготовку той же доказанно собственной VM/диска, сохраняя файлы и исходный результат создания. Обычный запуск и custody-команда recover настройку не продолжают. При неизвестном исходе создания читайте исходную операцию, а не принимайте VM по имени и не создавайте замену. Необязательный setup_failure различает сохранённый репозиторий с недоказанным происхождением (repository_unproven, нужна локальная проверка), отсутствие Python3/libc/поддержки исключительной публикации файловой системой (prerequisite_unavailable), необходимость исправить доступ или ref репозитория (repository_checkout_failed) и проверить диагностику фиксированной конфигурации гостя (configuration_failed). Доказанно опубликованный репозиторий сохраняет ветку и пользовательские изменения; перенаправленные Git-метаданные или существующий корень с недоказанным происхождением сохраняются с отказом, а не перезаписываются.

Работающий гостевой Unix API готов до получения необязательных workspace credentials и облачной регистрации. Ожидание облачного ответа не блокирует локальную проверку или остановку; смена runtime, поколения или прав запрещает применять устаревший ответ. Повторная подготовка использует заданные или точно привязанные сохранённые данные Git-автора; checkout публичного репозитория не ждёт необязательного запроса автора. Первоначальный private checkout по-прежнему требует текущих прав. Необязательное наблюдение remote.state различает unconfigured, enrollment_unavailable, connecting, connected, unavailable и refused; отсутствие наблюдения остаётся неизвестностью. Временный сбой регистрации не блокирует локально разрешённую работу. Существующее удалённое соединение восстанавливается без повтора команд; подтверждённый отказ закрывает эту удалённую авторизацию. Последующая регистрация перезагружает конфигурацию того же Unix-владельца без перезапуска принятых команд. Удалённой работе через MCP по-прежнему нужны текущие права и доступный маршрут.

Устанавливайте согласованные сборки сервера и companion. Их строгий контракт snapshot и результатов управления включает точную identity создания, готовность гостя и подтверждение native-остановки. Запись не считается наблюдённой до проверенного чтения. Используйте описанные выше явное обслуживание и резервное копирование; откат восстанавливает согласованные серверную базу, полное локальное состояние, хранилище SDK и бандлы вместе. Неподдерживаемый сохранённый формат владельца сохраняется для диагностики; старое облачное состояние остаётся архивным. Обновление сервера или пересборка CLI не заменяют код журнала и повтора уже работающего daemon или установленный исполняемый релиз. Фиксированная подготовка гостя обновляет общий сервис на месте. Если подтверждение не содержит доказательства старта, этот старт остаётся неподтверждённым. Читайте исходную операцию вместо перезапуска companion ради потерянного ответа. Выход клиента и потеря наблюдателя не разрешают физическую остановку VM; эта граница остаётся у явных stop, disable и обслуживания.

Хостовый CLI поддерживает create OWNER/REPO --ref BRANCH, start WORKSPACE_REF, resume-setup WORKSPACE_REF, stop WORKSPACE_REF, remove WORKSPACE_REF --confirm, observe WORKSPACE_REF, collect OPERATION_REF и operations CONTROLLER_REF через работающий приватный контроллер. observe читает только выбранный ресурс Local, а для GitHub — сохранённые management-метаданные его привязки, а не живую готовность провайдера или гостя. Оба пути не ждут полного native inventory Local. Для намеренного полного опроса используйте workspaces. Наблюдение проверяет текущую identity контроллера и соединения и точную привязку resource/provider, возвращая её актуальное поколение. Старая ссылка позволяет запросить свежее наблюдение, но не разрешает мутацию со старым поколением. Отсутствующая привязка, отказ доступа или сбой выбранного Local runtime дают явный отказ, а не переход к полному опросу. Передавайте возвращённые ссылки без изменений; обычные lifecycle-команды сами создают внутреннюю identity. Отдельный collect ORIGINAL_REQUEST_ID предназначен для привилегированных исходных запросов обслуживания или security custody. Новое создание требует доступной облачной регистрации маршрута и начальных прав Git. Уже допущенные VM можно запускать, останавливать и очищать офлайн в пределах текущих прав. Запуск требует включённого разрешения работы; подтверждённая владельцем очистка его не включает. Raw execution на хосте не поддерживается; команды и файлы используют гостевой moira-workspace или MCP. recover остаётся средством восстановления. Постоянный paired lifecycle использует run. После сбоя или перезагрузки регистрация при входе запускает выбранный релиз; run с тем же каталогом состояния также запускает его или подключается. Старый runner marker восстанавливается автоматически только под системной блокировкой и после подтверждения отсутствия обоих прежних процессов-владельцев. Политика, записи VM и неизвестные операции сохраняются без повтора. Живой, неизвестный или повреждённый владелец остаётся отказанным; не удаляйте marker вручную. Если service-status показывает сохранённую ошибку запуска, повтор run только читает состояние этой службы. После исправления предпосылки выполните явное восстановление обслуживания из Решения проблем, сохраняя исходный ID обслуживания, если он уже есть. Подключение клиента не повторяет инициализацию владельца. На macOS запуск также при необходимости монтирует существующий стандартный дисковый образ из того же каталога состояния. Перед работой проверяются native-привязка образа к точке монтирования, владелец тома и согласованная ёмкость без фиксированного запаса свободного места; потерянный ответ attach проверяется по наблюдаемой привязке. Пользовательское хранилище нужно смонтировать вручную. Отсутствующий образ или конфликт привязки по-прежнему запрещают запуск; новый диск не создаётся и данные не сбрасываются. Рост sparse-образа не требует заранее выделять всю логическую ёмкость или дополнительный запас на хосте. При уменьшении сохраняются минимальный размер APFS и требование вместить существующие данные; неопределённые физические изменения сохраняют исходный журнал изменения размера. Работа и doctor проверяют текущие права уже при запуске SDK. Установка, подготовка гостя и его регистрация ожидают фактического завершения; явное отключение и адресная отмена сохраняют физическое действие. Потеря родителя или наблюдателя освобождает наблюдение без нового намерения остановки. Фиксированные проверки метаданных и ограниченная диагностика doctor являются наблюдениями, а не доказательством завершения ожидающей операции. Локальный daemon отделяет связь с сервером от времени жизни VM. При сетевой ошибке/5xx он переподключается; удалённое состояние владельца недоступно до восстановления связи, а принятая работа сохраняется. Новые удалённые изменения отклоняются, а не ставятся в очередь. Адресный отказ ресурса остаётся в пределах этого запроса. Подтверждённый удалённый отзыв/смена identity устройства закрывает удалённый маршрут; локальное отключение остаётся физической политикой. Текущие права сохраняют силу; возврат сохранённого результата не повторяет эффект. Закрытие клиента run оставляет постоянную службу работающей; npm run local -- disable независимо останавливает собственную работу и сохраняет данные VM. Stop сохраняет файлы, а remove WORKSPACE_REF --confirm удаляет точную собственную VM. Неопределённый исход команды или правки сохраняется по собственной identity операции без автоматического повтора и не блокирует независимую работу. Перед повтором той же правки или изменением затронутых файлов проверьте сохранённый результат: ошибка доставки не доказывает, что запись не применена. Обычная остановка и запуск не требуют ручной синхронизации. Если восстановления требует сам владелец runtime, сначала подтвердите физическую остановку VM, затем выполните recover SPACE_ID --confirm с тем же каталогом состояния. Команда проверяет точную identity и сетевую политику без повтора задач; прежние задачи и неизвестные исходы сохраняются. Если признанный неопределённый исход возник во время первоначальной подготовки, VM остаётся с незавершённой подготовкой. Исправьте предпосылку и явно выполните resume-setup WORKSPACE_REF для той же VM; одно подтверждение не завершает настройку и не разрешает обычный start. Для потерянного владельца процессов команда recover --confirm требует выключенной работы, подтверждает физическую остановку и сохраняет задачи и данные. См. Решение проблем.

У локальных VM нет host mounts, общих skills, host MCP gateway или перенаправленных credentials, environment и agent sockets хоста. Внешняя политика SDK запрещает host/LAN/VPN/metadata/other-VM доступ и прямой egress; допускается только локально одобренный публичный egress через broker. Публичные SDK placeholders для API/GitHub в гостевых переменных не являются токенами пользователя. Конфигурация и успешное соединение с proxy сами по себе не доказывают физическую изоляцию. Для проверки host, LAN, VPN, metadata-сервиса и других VM нужны доступные контролируемые получатели по соответствующим направлениям; недоступность получателя не доказывает изоляцию. Содержимое кодспейса намеренно видно Moira; проверяйте возвращённый код перед запуском на компьютере.

Включение подключения GitHub для кодспейсов

Подключение GitHub для кодспейсов не связано с социальным входом через GitHub. Оно остаётся отключённым, пока не заданы все корректные значения GitHub App и хранилища учётных данных. Создайте GitHub App, включите истекающие user authorization tokens и «Request user authorization (OAuth) during installation», выдайте ему права на репозитории Codespaces (write), Codespaces lifecycle admin (write), Codespaces metadata (read), Contents (write), Pull requests (write) и Metadata (read), укажите точный API-путь Moira для callback и URL установки с GitHub slug приложения. Setup URL не нужен: после установки GitHub возвращает браузер на callback URL:

Terminal window
CODESPACE_GITHUB_APP_CLIENT_ID=<github-app-client-id>
CODESPACE_GITHUB_APP_CLIENT_SECRET=<github-app-client-secret>
CODESPACE_GITHUB_APP_CALLBACK_URL=https://moira.example.com/api/integrations/github/callback
CODESPACE_GITHUB_APP_INSTALL_URL=https://github.com/apps/<github-app-slug>/installations/new
CODESPACE_CREDENTIAL_VAULT_KEY=<случайный-64-значный-hex-ключ>
CODESPACE_CREDENTIAL_VAULT_KEY_VERSION=v1

Создайте отдельный ключ хранилища вне репозитория и поместите результат в незатреканное окружение деплоя:

Terminal window
openssl rand -hex 32
docker compose up -d

Origin callback должен совпадать с публичным origin Moira. Публичный callback использует HTTPS и не содержит query или fragment. Используйте client secret, созданный GitHub: placeholder, повторяющиеся символы и другие значения с низким разнообразием отклоняются. Ключ хранилища не генерируется автоматически и должен оставаться неизменным между перезапусками контейнера; после его замены существующие credentials подключения нельзя прочитать.

Если ключ или ciphertext потерян, обычные переподключение и отключение не могут подтвердить удалённый отзыв. Сначала удалите grant приложения Moira GitHub App в настройках GitHub. Затем вернитесь в Настройки → Разработка → Подключение GitHub и выберите Удалить после внешнего отзыва в карточке GitHub. Подтверждение удаляет нечитаемый локальный ciphertext; не подтверждайте, пока grant виден в GitHub. Если исходные ключ и версия восстановлены, Moira больше не предлагает восстановление для нечитаемого credential. Обычные Переподключить GitHub и Отключить снова доступны; оба действия точно отзывают читаемый предыдущий credential.

Такое же подтверждение внешнего отзыва появляется, если обновление могло вернуть новый credential, который Moira не смогла сохранить или отозвать. Перед подтверждением отзовите весь grant GitHub App; в этом состоянии переподключение и обычное отключение намеренно недоступны.

После выхода контейнера в healthy каждый пользователь открывает Настройки → Разработка → Подключение GitHub, нажимает Подключить GitHub и один раз авторизуется в GitHub. Если приложение ещё не установлено в аккаунте, браузер сразу переходит на страницу установки GitHub; после установки для нужных личных репозиториев настройки показывают подключение без повторной авторизации. Если возврат не пришёл, Проверить установку заново читает установку. Чтобы сменить аккаунт GitHub, отключитесь и подключитесь снова. Авторизация никогда не выполняется через MCP-инструмент или агента. Если настройка отсутствует или credential нужно обновить, пользователь возвращается на этот сайт.

Для GitHub Codespaces нужны CODESPACE_CODESPACES_ENABLED=true, действующие grants приложения и активный зарегистрированный сопряжённый контроллер. Если зарегистрировано несколько контроллеров, выберите возвращённую ссылку контроллера, даже когда доступен только один. Выбор не опрашивает каждый контроллер: обычный маршрут сообщает, может ли выбранный владелец принять запрос, и не подменяет его другим. Контроллер хранит журналы исходных операций и выполняет фиксированную подготовку через поставляемый gh, доверенный SSH и проверенный Linux payload. Облачная Moira сохраняет минимальные права ресурса/аккаунта и фиксированные вызовы API провайдера. Облачный Compose-коннектор не нужен. Выбранный контроллер проверяет личного плательщика и предложенные машины, затем сохраняет выбор машины и применимые настройки простоя и хранения до фиксированного запроса создания. Облако повторно проверяет текущие права и настройки, но не выбирает другую машину или контроллер.

Для обнаружения используйте codespace({ action: "list", provider: "github-codespaces" }), codespace({ action: "targets", provider: "github-codespaces" }) и codespace (setup_help). Список по умолчанию использует view: "actionable", включая известную незавершённую подготовку. Выберите view: "diagnostics" для неопределённых или недоступных идентичностей и ссылок исходных операций либо view: "history" для подтверждённо выведенных из эксплуатации сред. Эти представления есть и в Настройках. Диагностические идентичности не имеют поколения для lifecycle: прочитайте исходную операцию или запросите наблюдение, не выдумывая право изменения. Отказы провайдера остаются явными. Local не ждёт GitHub или биллинг. Биллинг загружается отдельно при открытии подраздела настроек GitHub; обновление сред его не читает. codespace (create) принимает выбранную цель; lifecycle/delete — возвращённую ссылку workspace. codespace (adopt) явно выбирает контроллер для уже наблюдаемой среды, а codespace (adopt_external) — контроллер и имя собственного внешнего окружения. Явный adopt может запустить остановленную среду и подготавливает её диск на месте. Ожидающая или неопределённая операция не подтверждает готовность гостя: сохраните её ссылку и используйте codespace (collect), не повторяя создание, запуск или установку.

Гость GitHub запускает проверенный локальный Unix API до необязательной облачной регистрации. Если первая регистрация недоступна, локальный CLI работает, а удалённые MCP-вызовы пока недоступны. После завершения исходной операции и подтверждения завершения её SSH-процессов выберите Продолжить подготовку либо вызовите codespace({ action: "lifecycle", workspace, operation: "resume_setup" }) с возвращённым наблюдением. Выбранный контроллер сравнит сохранённые исходные репозиторий/корень, время жизни гостя, установленный релиз и текущее назначение, затем продолжит фиксированную конфигурацию и регистрацию того же окружения. Он не переустанавливает payload, не запускает провайдера, не выполняет adopt и не создаёт другую VM. Смена времени жизни или прав запрещает продолжение. codespace (collect) только читает результат и не выполняет этот шаг подготовки.

После холодного перезапуска уже зарегистрированный гость GitHub с сохранённым правом продления открывает Unix API до удалённого продления. Временные сетевые ошибки и сбои хранилища повторяются в существующем цикле подключения без использования удалённого credential прежней жизни и без повтора работы. Подтверждённый отказ закрывает удалённые права. Последующая регистрация или продление сохраняет того же работающего Unix-владельца и принятые команды; сам холодный перезапуск может прервать процессы. Никогда не зарегистрированный гость не может заменить исходное доказательство после смены времени жизни. Сохраните окружение и проверьте исходную операцию через назначенный контроллер перед выбором другого lifecycle-действия.

Команды и файлы через MCP требуют доступного аутентифицированного гостя. Обычный маршрут не запускает VM и не открывает SSH. Локальный Unix API готов независимо от облачного соединения, но это не доказывает доступность удалённого маршрута. Подтверждённый отказ регистрации 401/403 прекращает использование credential; обычная сетевая потеря допускает переподключение. codespace_terminal (collect) читает исходный результат, codespace_terminal (output) и codespace_terminal (stop) адресуют возвращённый процесс. Потеря облачной связи или клиента не отменяет принятую команду.

Агент в кодспейсе действует как обычный пользователь Codespace: он может читать репозиторий, использовать сеть и читать секреты, настроенные для этого Codespace. Изоляция Moira защищает сервер Moira и других пользователей, а не кодспейс от агента, которого авторизовал его владелец. Если настройка не завершена, отказ содержит те же применимые ссылки на Настройки, создание репозитория и консоль провайдера, что и setup_help, а при настроенном URL — также ссылку на установку приложения; авторизация при этом не запускается. Кодспейс остаётся личным, а совместная работа идёт через ветки системы контроля версий.

Теми же кодспейсами пользователи управляют в карточке Среды разработки раздела Настройки → Разработка → GitHub Codespaces: создают кодспейс для одобренного репозитория, запускают или останавливают его (остановка сохраняет данные репозитория) и удаляют после явного подтверждения. Активность и остановку по простою определяет GitHub: карточка Автоматическая приостановка в том же разделе задаёт codespaces.auto_stop_enabled (по умолчанию включена) и codespaces.idle_timeout_minutes (по умолчанию 30, от 5 до 240) передаются при создании нового Codespace. Выключение запрашивает максимум GitHub — 240 минут, а не неограниченный runtime. Существующие Codespaces сохраняют параметры провайдера. GitHub наблюдает редактор, браузер и ввод/вывод терминала; команда без вывода может быть прервана остановкой по простою. Local следует текущему разрешению и политике владельца компьютера. Текущие ресурсы и биллинг GitHub показываются отдельно; недоступный биллинг не отзывает доступ к workspace. Админ → Настройки → Кодспейсы — это чтение конфигурации с обновлением, без переключателей остановки жизненного цикла.

Health сообщает готовность конфигурации disabled, misconfigured либо ready. ready не доказывает подключение конкретного контроллера или гостя. Get/list ресурса и чтение исходной операции отдельно возвращают текущие наблюдения владельца. Восстановите назначенного владельца вместо попытки исправить подготовку обычным файловым вызовом.

Отключение запрещает локальное использование до отзыва доступа в GitHub. Если GitHub временно недоступен, страница показывает незавершённый отзыв, а кнопка Отключить повторяет операцию по точной зашифрованной capability; credential не возвращается в браузер или модели.

Подключение MCP-клиента

MCP-эндпоинт — это ваш хост плюс /mcp:

http://localhost:8080/mcp

Добавьте его как MCP-сервер в ваш AI-клиент и пройдите OAuth-аутентификацию. Настройку клиента смотрите в Быстром старте.

Обновление и восстановление

Для обычного обновления не требуется искать версию или запускать скрипт из репозитория:

Terminal window
docker compose pull
docker compose up -d
docker compose ps

Используйте опубликованный актуальный тег образа. Для обычного канала публичных релизов задайте:

Terminal window
MOIRA_IMAGE=ghcr.io/moira-mcp/moira:latest

До запуска миграций нового self-host образа startup guard создаёт online backup существующей SQLite БД и проверяет PRAGMA integrity_check. База вместе с соответствующим prompt-manifest.json сохраняется в data/.moira-startup-backups/current/, а предыдущие состояния ротируются в previous-1/ и previous-2/. При настоящем первом запуске БД ещё нет, поэтому backup не создаётся.

В current-слоте хранится persistent-маркер незавершённой инициализации. Если контейнер или хост прерывается до фиксации результата, следующий запуск сначала восстанавливает проверенный slot и только затем создаёт новый backup, поэтому частично мигрированная БД не становится новым baseline. На первом запуске отдельный marker без фиктивной backup-БД фиксирует, что базы раньше не было. После прерывания повторный запуск удаляет только незавершённые новую БД, WAL/SHM и prompt manifest и начинает с чистого состояния; успешная инициализация удаляет marker.

Если инициализация схемы, промптов или workflow завершается ошибкой после записи данных, guard удаляет WAL/SHM, восстанавливает проверенные БД и manifest, пишет /tmp/init-failed и не запускает MCP, API и nginx. Recovery-копия сохраняется. После исправления конфигурации или каталога проверьте состояние и повторите запуск:

Terminal window
docker compose logs moira
docker compose exec -T moira sqlite3 /app/data/moira.db 'PRAGMA integrity_check;'
docker compose exec -T moira sqlite3 /app/data/.moira-startup-backups/current/moira.db 'PRAGMA integrity_check;'
docker compose restart moira
docker compose ps

latest намеренно следует за текущим публичным релизом. Автоматическое восстановление защищает постоянные данные, но не может заменить сам Docker-образ. Если образ не доходит до startup guard, БД не мигрировалась. Временно укажите в MOIRA_IMAGE предыдущую версию из GitHub Releases, выполните docker compose up -d, а после исправленного релиза вернитесь на latest.

Обновление, изменяющее встроенный workflow, может оставить приостановленное внутри него выполнение без возможности продолжиться. Старт называет такие выполнения до применения обновления — workflow, выполнение и ноду, на которой каждое стоит, — поэтому они видны в docker compose logs moira, пока прежние определения ещё на месте. Предупреждение никогда не останавливает обновление. Выполнение, ставшее непригодным из-за изменения workflow, можно затем восстановить через execution({ action: 'diagnose', ... }) и execution({ action: 'recover', ... }); выполнение, чей workflow обновление удаляет, восстановить нельзя — возобновляться не на чем, — и строка сообщает, какой это случай. Отсутствие предупреждения означает, что ни одно приостановленное выполнение не пострадает, только когда анализ затронутых запусков действительно выполнялся. Невыполненная проверка или отсутствие логов не доказывают безопасного продолжения; изучите диагностику выбранного обновления.

Когда обнаружение конфликта создало локальный bundle в data/.moira-reconciliation/pending, выполните его AGENT INSTRUCTIONS через одноразовые Compose CLI-контейнеры. Сам CLI не останавливает и не перезапускает сервисы и не подменяет snapshot базы. Он использует только локальные файлы — без --force, MCP, HTTP API и UI-транспорта. Инициализация завершается fail-closed: после восстановления БД контейнер останавливается, а MCP, API и nginx остаются недоступны. После применения bundle финальная команда docker compose up -d запускает остановленный контейнер обычным способом.

Terminal window
docker compose run --rm moira npm run reconcile -- status
docker compose run --rm moira npm run reconcile -- diff --reference owner/slug
# Прочитайте previous.json, current.json и incoming.json по выведенным путям.
# Запишите revision-bound решение current, incoming или merged для каждого конфликта:
docker compose run --rm moira npm run reconcile -- choose \
--reference owner/slug --selection incoming --revision REVISION \
--rationale "Incoming заменяет локальный эксперимент"
docker compose run --rm moira npm run reconcile -- apply
docker compose up -d

Для слияния возьмите incoming.json за основу, перенесите только всё ещё нужное локальное намерение из previous.json → current.json, проверьте полный merged state через reconcile validate и передайте его в choose --selection merged --file .... choose меняет только локальный decisions manifest. Только apply изменяет базу и отказывается работать с неполным или устаревшим manifest.

Необязательный preflight до остановки

Оператор может заранее проверить точный образ на изолированной копии БД, скачав advanced helper из этого релиза. Это необязательный путь; обычное обновление использует две Compose-команды выше. CLI sqlite3 на хосте нужен только для advanced-варианта.

Terminal window
RELEASE_VERSION=x.y.z
TARGET_IMAGE=ghcr.io/moira-mcp/moira:${RELEASE_VERSION}
curl -fLo self-host-upgrade.sh "https://raw.githubusercontent.com/moira-mcp/moira/v${RELEASE_VERSION}/scripts/self-host-upgrade.sh"
chmod +x self-host-upgrade.sh
./self-host-upgrade.sh preflight "$TARGET_IMAGE"
./self-host-upgrade.sh upgrade "$TARGET_IMAGE"

Helper сохраняет проверенный snapshot и диагностическую копию в .moira-upgrade/; если замена или health check завершились ошибкой, используйте ./self-host-upgrade.sh rollback. Advanced-путь записывает точный образ в .env; чтобы вернуться в обычный release channel, после проверки задайте MOIRA_IMAGE=ghcr.io/moira-mcp/moira:latest.

Владельцы файлов и изображения уведомлений

Для нативных вложений и рендера прогресса запустите сопряжённый контроллер. Само владение этими коммуникационными файлами не требует Local VM или включённой физической Local-возможности. Если зарегистрировано несколько активных контроллеров, выберите возвращённую ссылку контроллера, даже когда доступен только один. Выбранная identity сохраняется: недоступность маршрута не разрешает другого владельца и не доказывает, что предыдущая отправка никогда не выполнялась. При обновлении согласованного исполняемого релиза сохраняйте приватные неизменяемые файлы и журнал доставки владельца. Публикации workspace остаются у своего владельца. Архивы materialize используют неизменяемую публикацию и исходный результат сопряжённого контроллера; их отдельный текстовый fallback execution (materialize) не требует владельца файлов.

Обычный текст, напоминания ожидания и доверенная доставка PIN работают без владельца файлов. Явная доставка файла сообщает о недоступном владельце вместо скачивания в облако. Необязательная картинка прогресса может быть пропущена с независимой доставкой текста. COMMUNICATION_OWNER_UNAVAILABLE при выдаче или чтении PNG возвращает HTTP 503: восстановите сопряжённое соединение.

Поставляемый ingress передаёт /api/communication/ потоком без буферизации запроса/ответа, временных body-файлов и общего потолка размера тела. Сохраняйте эту конфигурацию. Бинарное тело содержит метаданные с framing и непрозрачные байты источника. Публичные owner-file ссылки предоставляют доступ к файлу: не записывайте их в access logs. Бинарный артефакт расширения выбирается по digest; секреты канала остаются у доверенного облачного транспорта.

Включение расширений

Для расширений нужен checkout исходников: образ сопутствующего runner собирается локально, а опубликованный образ приложения Moira остаётся без изменений. Из корня репозитория выполните:

Terminal window
cp .env.example .env
mkdir -p extensions
cp -R examples/extensions/webhook-notify extensions/

В скопированном манифесте замените зарезервированный example.com и в верхнеуровневом permissions.network, и в permissions.network канала коммуникации на точный хост своего эндпоинта. Разрешения ноды и канала независимы. Адрес, получателя уведомлений по умолчанию и остальные значения каждый пользователь заполняет на странице настроек Moira. Затем добавьте адрес runner в .env и включите профиль:

Terminal window
printf '\nMOIRA_EXTENSION_RUNNER_URL=http://moira-extension-runner:9110\n' >> .env
docker compose --profile extensions up -d --build

Профиль собирает runner, монтирует ./extensions в его контейнер только для чтения, ждёт готовности runner и затем запускает Moira. Обычный docker compose up -d runner не запускает.

Runner и Moira загружают каталог расширений при старте. После изменения установленных бандлов:

Terminal window
docker compose --profile extensions up -d --force-recreate --wait moira-extension-runner
docker compose --profile extensions restart moira

Причины отказа и живой каталог можно проверить, не публикуя порт runner:

Terminal window
docker compose --profile extensions logs moira-extension-runner
docker compose --profile extensions exec moira-extension-runner curl -fsS http://127.0.0.1:9110/health

Пустой каталог допустим. Health-ответ перечисляет загруженные типы нод и ID каналов коммуникации. Если Moira сообщает о недоступном реестре, проверьте URL, health и логи, затем перезапустите обе службы в показанном порядке. Если отсутствует отдельный вклад расширения, найдите причину отказа его манифеста. Полный контракт манифеста, SDK, разрешений, настроек, редактора, доставки, результатов, ошибок и безопасности описан в Написании расширения.

Добавление собственных workflow-флоу

В образе есть встроенный каталог workflow в ./workflows/production. Чтобы дополнительно загрузить свои флоу, задайте WORKFLOWS_DIRS — список базовых каталогов каталога через двоеточие (каждый со структурой flows/<uuid>.json):

Terminal window
WORKFLOWS_DIRS=./workflows/production:./my-private-workflows/production

Каталоги объединяются и дедуплицируются по (owner, slug). Поздний каталог переопределяет ранний при коллизии, поэтому каталог, указанный последним, может расширять или перекрывать встроенный. Не задан → только встроенный ./workflows/production. Смонтируйте дополнительный каталог в контейнер (например, через volume в compose), чтобы путь существовал во время выполнения.

Сборка из исходников

Локальная сборка — альтернатива для контрибьюторов, которым нужно изменить образ. В docker-compose.yml закомментируйте строку image: и раскомментируйте блок build:, затем:

Terminal window
docker compose up -d --build

Связанное