Как запустить KiroCrew на VPS через Docker

Почему стоит размещать KiroCrew на VPS, а не на ноутбуке

Самостоятельный хостинг KiroCrew оправдан только на машине, которая работает круглосуточно, поэтому VPS подходит для этого лучше, чем ноутбук. KiroCrew хранит историю сессий, семантическую память, запланированные задачи и очередь подтверждений на диске, перезагружая эти данные при каждом запуске процесса. Это не поможет, если процесс не запущен в 03:00, когда должна выполниться запланированная задача, а закрытый ноутбук её не выполнит.

KiroCrew — это агентская рабочая среда с открытым исходным кодом от команды Kiro, распространяемая по лицензии Apache 2.0, первые публичные релизы которой вышли в начале августа 2026 года. Один процесс, называемый шлюзом (gateway), управляет состоянием и предоставляет веб-панель управления на порту 5476. Доступ к этому шлюзу осуществляется через панель управления, kirocrew CLI или чат-каналы, такие как Slack. Шлюз — это единственный компонент, который вы размещаете самостоятельно, поэтому данное руководство посвящено обеспечению его работоспособности, ограничению доступа из публичного Интернета и возможности восстановления после неудачного обновления.

Две вещи, которые нужно знать перед началом. KiroCrew управляет kiro-cli, что требует однократного входа в систему с учетной записью Kiro, а агентские вычисления оплачиваются согласно тарифному плану Kiro, поэтому по состоянию на август 2026 года это не является автономной (offline) установкой. Проекту всего несколько недель. Исходите из того, что вам может потребоваться откат изменений, и устанавливайте его так, чтобы это было возможно. Если вы ранее не запускали агентов на сервере, в статье запуск агента для программирования на VPS описаны базовые принципы, на которых строится это руководство. Если агентская часть для вас в новинку, сначала ознакомьтесь с материалом что такое агентский цикл, его инструменты и память, чтобы представленные ниже действия воспринимались как осознанные решения, а не как магические заклинания.

Что требуется KiroCrew и где хранятся данные о состоянии

Для нативной установки необходим Python 3.10 или новее (рекомендуется версия 3.12), Node.js 18 или новее, если вы собираете панель управления из исходного кода, а также kiro-cli, который при первом запуске устанавливается и настраивается автоматически. Для контейнерной установки ничего из этого на хосте не требуется. Нужен только Docker. Это основная причина предпочесть данный способ.

Состояние хранится в ~/.kiro/crew, а переменная окружения KIROCREW_HOME позволяет перенести его в другое место. Что находится внутри:

• config.json: настройки шлюза и учетные данные каналов чата.
• .env: секреты.
• workspace/memory/: настройки, заметки по проекту и история чатов.
• memory.db и memory_index.db: семантический и полнотекстовый индексы.
• models/: модель эмбеддингов, загружаемая при первом запуске.
• gateway.log и security_events.jsonl: журнал выполнения и журнал событий безопасности.

Этот каталог и есть сама установка. Скопируйте его на новый VPS, и ваш агент будет перенесен. Именно поэтому раздел о резервном копировании ниже важнее, чем раздел об установке.

Планируйте ресурсы исходя из объема диска, а не оперативной памяти. Шлюз — это процесс на Python; нагрузку на систему создает то, что запускает агент: сборка или набор тестов. Каталог состояния растет вместе с историей чатов, а модель эмбеддингов загружается при первом запуске. Поэтому через несколько недель оцените объем данных на своем сервере с помощью du -sh ~/.kiro/crew, вместо того чтобы доверять цифрам, опубликованным в первый месяц жизни проекта. Сравните это с runtime, который выделяет каждому воркеру отдельный контейнер и браузер, где самостоятельный хостинг AI-коллег OpenBot делает расчет оперативной памяти более приоритетной задачей, чем расчет дискового пространства.

Какой из трех путей установки выбрать

Проект предлагает три варианта. Однострочный установщик загружает wheel-пакет и добавляет kirocrew в ваш PATH:

curl -fsSL https://download.crew.kiro.dev/cli.sh | sh

Он принимает флаг канала и флаг версии:

curl -fsSL https://download.crew.kiro.dev/cli.sh | sh -s -- --channel insider
curl -fsSL https://download.crew.kiro.dev/cli.sh | sh -s -- --version 0.1.3

Контейнерный образ публикуется по адресу ghcr.io/kirodotdev/kirocrew для архитектур linux/amd64 и linux/arm64 под каждым тегом. Сборка из исходного кода — это git clone плюс make build; она предназначена для тех, кто вносит изменения в код, а не для тех, кто его запускает.

Используйте контейнер. Нативная установка размещает Python-пакеты, Node и kiro-cli на том же хосте, где работают другие ваши сервисы. В случае неудачного обновления вам придется исправлять всё вручную. Контейнер хранит среду выполнения в одном образе, а состояние — в одном томе. Это позволяет выполнить откат, просто сменив тег и перезапустив сервис.

Закрепляйте образ за тегом релиза, а не за stable

В примере самого проекта используется тег stable:

docker run -d --name kirocrew \
  -p 127.0.0.1:5476:5476 \
  -v kirocrew-home:/home/kirocrew \
  ghcr.io/kirodotdev/kirocrew:stable

stable — это динамический тег. Он всегда указывает на актуальный стабильный релиз, поэтому при следующем выполнении pull версия может измениться без вашего участия, а сам тег не сохраняет информацию о том, какая именно версия была загружена. Теги версий неизменяемы, поэтому используйте их для фиксации. Самый свежий релиз на 6 августа 2026 года — 0.1.3, опубликованный 5 августа 2026 года. Также существует тег nightly, что для такого молодого проекта означает, что код менялся сегодня утром.

Напишите /opt/kirocrew/compose.yaml:

services:
  kirocrew:
    image: ghcr.io/kirodotdev/kirocrew:0.1.3
    container_name: kirocrew
    restart: unless-stopped
    ports:
      - "127.0.0.1:5476:5476"
    volumes:
      - kirocrew-home:/home/kirocrew

volumes:
  kirocrew-home:

Запустите его, а затем проверьте эндпоинт проверки работоспособности (health endpoint), который образ также использует для своего HEALTHCHECK:

cd /opt/kirocrew
docker compose up -d
docker compose ps
curl -s http://127.0.0.1:5476/api/health

docker compose ps должен сообщить, что контейнер исправен (healthy), примерно в течение минуты, а /api/health отвечает без токена (как и /api/live с /api/ready, что и делает их пригодными для использования в качестве проб). Если состояние остаётся starting, прочитайте docker logs kirocrew, прежде чем что-либо менять. При первом запуске скачивается модель эмбеддингов, поэтому при медленном соединении первый запуск может занять много времени.

Поддержание работы с помощью systemd

restart: unless-stopped возвращает контейнер в рабочее состояние после сбоя или перезагрузки, при условии, что сам Docker запускается при старте системы. Unit-файл делает эту зависимость явной и предоставляет одну команду для остановки всего стека перед выполнением резервного копирования. В запуске стека Docker Compose при загрузке описан общий шаблон. Вот как это выглядит в стиле KiroCrew в /etc/systemd/system/kirocrew.service:

[Unit]
Description=KiroCrew gateway
Requires=docker.service
After=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/opt/kirocrew
ExecStart=/usr/bin/docker compose up -d
ExecStop=/usr/bin/docker compose down
TimeoutStartSec=0

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now kirocrew
systemctl status kirocrew

systemctl status kirocrew должен содержать active (exited), что является корректным результатом для этого юнита. Type=oneshot с RemainAfterExit=yes используется здесь потому, что docker compose up -d завершается сразу после запуска контейнера: systemd отслеживает факт того, что стек поднят, а не конкретный процесс в foreground. Если написать Type=simple, systemd увидит немедленное завершение команды, пометит сервис как нерабочий и либо прекратит попытки, либо уйдет в цикл перезапуска в зависимости от настройки Restart=. Для нативной установки проект поставляет собственный аналог, kirocrew service install, который создает /etc/systemd/system/kirocrew.service и запускает шлюз от имени вашего пользователя. Не запускайте оба юнита одновременно. Более подробно эта тема раскрыта в сервисах и таймерах systemd на VPS. Юнит, который не может перезапуститься, не подает сигналов, пока вы его не настроите, поэтому добавьте обработчик OnFailure=, который отправляет уведомление на ваш сервер ntfy, и вы узнаете о нерабочем шлюзе через телефон, а не из отчета по расписанию, которое так и не выполнилось.

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

Контейнер запускает шлюз, но среда выполнения агента еще не авторизована. Выполните вход внутри контейнера:

docker exec -it kirocrew kiro-cli login

Команда выведет код устройства и URL-адрес, который нужно открыть в вашем браузере. Затем создайте токен панели управления:

docker exec kirocrew kirocrew token --ttl 2h

URL-адрес панели управления — http://localhost:5476/?token=<the token>. Срок действия токенов ограничен: сессии по умолчанию длятся один час, а максимально допустимое значение согласно документации составляет двадцать часов. Если панель управления загружается пустой или сразу перенаправляет вас обратно на страницу входа, это обычно означает, что срок действия токена истёк; в этом случае создайте новый. Никогда не отправляйте токен в тикеты или чаты, так как любой, кто им завладеет, получит доступ к вашему агенту.

Доступ к панели управления через SSH без публикации порта 5476

Еще раз взгляните на адрес привязки в примере проекта: -p 127.0.0.1:5476:5476. Внутри контейнера шлюз слушает 0.0.0.0, так как он должен быть доступен через проброс портов, но само отображение публикует его только на loopback-интерфейсе хоста. Удалите префикс 127.0.0.1:, и шлюз окажется в открытом доступе для любого, кто просканирует этот порт. Правила межсетевого экрана вас не спасут: Docker публикует порты, создавая правила DNAT, которые обрабатываются до фильтрации ufw, поэтому ufw deny 5476 никак не влияет на опубликованный порт. В обходе Docker-портами ufw подробно описан этот механизм.

Вместо этого пробросьте порт через SSH со своего ноутбука:

ssh -N -L 5476:127.0.0.1:5476 you@your-server.example.com

Оставьте этот процесс запущенным и откройте http://localhost:5476/?token=<the token> локально. Чтобы автоматизировать проброс при каждом подключении, добавьте его в ~/.ssh/config:

Host your-server.example.com
    LocalForward 5476 127.0.0.1:5476

Если порт 5476 уже занят на вашем ноутбуке, измените только левое число: ssh -N -L 45476:127.0.0.1:5476 you@your-server.example.com, затем перейдите по адресу http://localhost:45476/?token=.... Вам придется выстраивать такие пробросы один за другим, как только второй агент начнет использовать сервер, поскольку самостоятельный хостинг open-kritt для сканирования безопасности размещает еще одну панель управления, доступную только через loopback, на том же сервере на порту 5173.

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

docker cp kirocrew:/home/kirocrew/.kiro/crew/config.json .
# edit config.json here
docker cp config.json kirocrew:/home/kirocrew/.kiro/crew/config.json
docker exec -u 0 kirocrew chown kirocrew:kirocrew /home/kirocrew/.kiro/crew/config.json
docker restart kirocrew

Для доступа с телефона проект предлагает tailscale serve от Tailscale. Он оставляет панель внутри вашей tailnet, а не на общедоступном имени хоста. Предпочтительнее использовать этот вариант, а не публичный reverse proxy. Токен передаётся в URL, а URL записывается в каждый access log на всём пути запроса. Это правило относится к тому, что находится за портом, а не к самому порту: например, Halcyon, который перестраивает библиотеку Jellyfin в доступный для просмотра видеомагазин в стиле 90-х, предназначен для открытия другими пользователями и подходит для reverse proxy, а шлюз, способный выполнять команды на вашем сервере, — нет.

Ограничьте радиус поражения агента до минимума

При первом запуске контейнер проверяет поддержку песочницы, и от этого результата зависит, сможет ли агент выполнять какие-либо действия. Если изоляция пространств имен (namespaces) доступна, подпроцессы агента запускаются изолированно. Если она недоступна, а переменная KIROCREW_ALLOW_UNSANDBOXED=1 не задана, выполнение будет отклонено вместо запуска без ограничений. Поэтому, если шлюз выглядит работоспособным, но все задачи зависают, причина обычно кроется именно в этом. Решение фиксируется в docker logs kirocrew при первом запуске. Проект также предоставляет профиль seccomp (secure computing mode), который можно применить:

curl -fsSL https://raw.githubusercontent.com/kirodotdev/KiroCrew/main/docker/seccomp/kirocrew-seccomp.json \
  -o /opt/kirocrew/kirocrew-seccomp.json

    security_opt:
      - seccomp:./kirocrew-seccomp.json

Если вы всё же задаете KIROCREW_ALLOW_UNSANDBOXED=1, четко осознавайте последствия: теперь контейнер является единственной границей между агентом и вашим сервером. Предупреждение проекта стоит повторить полностью. Не монтируйте пути хоста, которые вы не доверили бы агенту напрямую. На практике это исключает Docker socket, любые bind-монтирования / и любые каталоги, содержащие данные других сервисов.

Остальное — это общие правила, применимые к любому агенту, которому разрешено выполнять команды. Ограничьте его учетные данные одним репозиторием или одним бакетом, который ему необходим; никогда не используйте персональный токен с правами доступа ко всей учетной записи. Запускайте агент от имени выделенного пользователя, в домашнем каталоге которого больше ничего нет — именно для этого предназначено руководство пользователи с минимальными привилегиями на VPS. Когда агент пишет код, а затем исполняет его, предоставьте ему машину, которую не жалко сломать: одноразовая виртуальная машина для агентов-разработчиков является более надежной границей, чем любой флаг в этом файле compose, так как вы удаляете её целиком вместо очистки. Те же соображения лежат в основе безопасного запуска OpenClaw на VPS и самостоятельного хостинга агента Hermes на VPS. Инструменты также увеличивают радиус поражения: предоставление агенту доступа к веб-поиску превращает каждую загруженную страницу в недоверенный ввод, поэтому настройка агента на ваш собственный экземпляр SearXNG — это решение не только техническое, но и направленное на предотвращение prompt injection. Запланированные задачи также расходуют средства, пока вы спите, так как инференс оплачивается по вашему тарифному плану Kiro, поэтому установите лимиты, описанные в контроль расходов на AI-агента на VPS, прежде чем добавлять ночные задания.

Создавайте резервную копию тома с данными перед каждым обновлением

Сначала определите фактическое имя тома. Compose добавляет к именованным томам префикс с именем проекта (по умолчанию это имя директории), поэтому том, объявленный как kirocrew-home в /opt/kirocrew/compose.yaml, создается с именем kirocrew_kirocrew-home:

docker volume ls

Остановите шлюз перед копированием любых данных. memory.db и memory_index.db — это базы данных SQLite. Копирование базы данных в процессе записи может привести к захвату незавершенной транзакции, что при восстановлении сделает файл поврежденным. Инструкции по миграции самого проекта содержат аналогичное требование: перемещайте данные только при остановленных шлюзах. Это правило остановки перед копированием не является специфичным для KiroCrew. Если на сервере также работает фотохостинг, сравнение PhotoPrism и Immich содержит точные команды резервного копирования, необходимые для каждого из этих приложений.

sudo systemctl stop kirocrew
docker run --rm -v kirocrew_kirocrew-home:/data:ro -v "$PWD":/backup \
  alpine tar czf /backup/kirocrew-2026-08-06.tgz -C /data .
sudo systemctl start kirocrew

Скопируйте архив за пределы сервера. Восстановление выполняется той же командой при остановленном контейнере, но с заменой tar xzf на tar czf:

sudo systemctl stop kirocrew
docker run --rm -v kirocrew_kirocrew-home:/data -v "$PWD":/backup \
  alpine tar xzf /backup/kirocrew-2026-08-06.tgz -C /data
sudo systemctl start kirocrew

Перенос на новый хост отличается от восстановления на текущем месте, и проект содержит по этому поводу четкие указания. История чатов и заметки проекта в workspace/memory/ переносятся полностью, как и два файла базы данных вместе с config.json. PID-файлы, журнал событий безопасности и .env привязаны к старому хосту, поэтому их следует оставить, а секреты на новом сервере нужно ввести заново.

Как выполнить откат после неудачного обновления

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

sudo systemctl stop kirocrew
# take the backup here, as above
sudo nano /opt/kirocrew/compose.yaml   # set the new image tag
sudo systemctl start kirocrew
docker compose -f /opt/kirocrew/compose.yaml ps
curl -s http://127.0.0.1:5476/api/health

docker compose up -d загружает образ, если его ещё нет на сервере, поэтому редактирование тега — это и есть всё обновление. Откат выполняется в той же последовательности с использованием старого номера версии. Вы получите именно тот образ, который был до этого, так как теги версий неизменяемы.

Бинарный файл откатывается корректно. Проблемы могут возникнуть с состоянием данных. Более новая версия шлюза может изменить config.json или перенести базы данных в памяти в формат, который старая версия не сможет прочитать. По состоянию на август 2026 года путь для понижения версии не задокументирован. Если старый образ запускается, но работает некорректно, не пытайтесь его отлаживать. Остановите его, восстановите резервную копию, созданную до обновления, и начните заново. Именно поэтому резервное копирование выполняется в первую очередь, и именно поэтому привычка сначала обновляться, а потом делать бэкап не работает в столь молодом проекте.

Что здесь не подтверждено

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

Стоит самостоятельно протестировать два сценария, прежде чем полагаться на них в работе. Во-первых, проверяет ли понижение версии (downgrade) состояние, записанное более новой версией: попробуйте это на копии тома, пока это не критично, а не во время сбоя. Во-вторых, как ведет себя шлюз, когда срок действия входа Kiro истекает в момент запуска запланированной задачи. Оба случая — это типичные шероховатости, которые в молодых проектах устраняются в фоновом режиме между релизами, и оба легко проверить прямо сейчас.

FAQ

Почему панель управления KiroCrew не открывается по публичному IP-адресу моего сервера?

Потому что в опубликованном примере порт привязан к интерфейсу loopback. -p 127.0.0.1:5476:5476 пробрасывает порт контейнера только на адрес loopback хоста, что сделано намеренно. Получить доступ можно через перенаправление порта по SSH с помощью ssh -N -L 5476:127.0.0.1:5476 you@your-server, после чего откройте http://localhost:5476/?token=<token> на вашем локальном компьютере. Удаление префикса 127.0.0.1: сделает шлюз доступным из публичного интернета, при этом правило брандмауэра не ограничит к нему доступ, так как правила DNAT для опубликованных портов Docker обрабатываются до того, как ufw отфильтрует трафик.

Где KiroCrew хранит данные и что нужно резервировать?

Всё находится в ~/.kiro/crew, что внутри образа контейнера соответствует /home/kirocrew/.kiro/crew, а KIROCREW_HOME позволяет изменить это расположение. Создавайте резервную копию всей директории или всего тома Docker при остановленном шлюзе. memory.db и memory_index.db — это базы данных SQLite, поэтому копия, сделанная во время записи данных шлюзом, может оказаться несогласованной. При переносе на новый хост workspace/memory/, два файла баз данных и config.json переносятся целиком, в то время как PID-файлы, журнал событий безопасности и .env относятся к старому хосту.

Стоит ли использовать тег stable или тег версии?

Используйте тег версии. stable перемещается при каждом выпуске новой версии, поэтому версия, которую вы используете, может измениться без вашего ведома при следующем pull, а сам тег не дает информации о том, что именно запущено. Теги версий, такие как 0.1.3, неизменяемы, и именно это обеспечивает работу отката: вы возвращаете старый номер версии и получаете идентичный образ. По состоянию на 6 августа 2026 года новейшим релизом является 0.1.3.

Почему мой агент отказывается выполнять какие-либо команды?

При первом запуске контейнер проверяет поддержку песочницы (sandbox). Если он не может изолировать подпроцессы агента, а переменная KIROCREW_ALLOW_UNSANDBOXED=1 не установлена, он отказывается их выполнять, вместо того чтобы запускать без ограничений. В результате шлюз выглядит работоспособным, но все задачи зависают. docker logs kirocrew показывает решение о выборе песочницы, принятое при первом запуске. Установка этой переменной делает контейнер единственной границей между агентом и хостом, поэтому, если вы её устанавливаете, не монтируйте ничего, что вы не доверили бы агенту напрямую.

Нужна ли учетная запись Kiro для самостоятельного хостинга KiroCrew?

Да, по состоянию на август 2026 года. KiroCrew — это свободное ПО под лицензией Apache 2.0, но оно работает с kiro-cli, что требует однократного входа в систему, а инференс агента оплачивается согласно тарифному плану Kiro. Внутри контейнера выполните docker exec -it kirocrew kiro-cli login и подтвердите код устройства в браузере. Пока этот вход не выполнен, шлюз запускается и панель управления загружается, но агенту не с чем взаимодействовать.