KiroCrew на VPS: постійний agent у Docker

Чому варто розміщувати KiroCrew на VPS, а не на ноутбуці

Self-hosting KiroCrew має сенс лише на машині, яка ніколи не переходить у режим сну. Тому VPS підходить для нього, а ноутбук — ні. KiroCrew зберігає на диску історію сеансів, семантичну пам’ять, заплановані завдання та чергу підтверджень, а після перезапуску процесу завантажує всі ці дані. Це не допоможе, якщо процес не запущений о 03:00, коли має виконуватися заплановане завдання. Закритий ноутбук не запускає цей процес.

KiroCrew — це open source робочий простір для агентів від команди Kiro, ліцензований за Apache 2.0. Перші публічні релізи вийшли на початку August 2026. Один процес, який називається gateway, зберігає стан і надає вебпанель на порту 5476. Ви можете звертатися до цього gateway через вебпанель, через kirocrew CLI або через канал обміну повідомленнями, наприклад Slack. Ви self-hosting лише gateway. Тому цей посібник присвячено підтриманню його роботи, недоступності з публічного інтернету та відновленню після невдалого оновлення.

Перед початком потрібно знати дві речі. KiroCrew запускає kiro-cli, для якого потрібен одноразовий вхід за допомогою облікового запису Kiro. Виконання агентів оплачується за тарифним планом Kiro, тому станом на August 2026 це не offline-конфігурація. Проєкту також лише кілька тижнів. Припускайте, що вам доведеться виконати rollback, і встановіть його так, щоб це було можливо. Якщо ви ще не запускали агента на сервері, у матеріалі запуск агента для написання коду на VPS описано базові правила, на яких ґрунтується цей посібник.

Що потрібно KiroCrew і де зберігається його стан

Для нативного встановлення потрібен Python 3.10 або новіший (проєкт рекомендує 3.12), Node.js 18 або новіший, якщо ви збираєте dashboard із вихідного коду, а також kiro-cli, який встановлюється та виконує вхід під час першого запуску. Для встановлення в контейнері на хості нічого з цього не потрібно. Потрібен Docker. Це головна причина надати перевагу такому способу.

Стан зберігається в ~/.kiro/crew, а змінна середовища KIROCREW_HOME дає змогу перенести його в інше місце. Усередині містяться:

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

Цей каталог і є встановленою системою. Скопіюйте його на новий VPS — і ви перенесете свого агента. Саме тому розділ про резервне копіювання нижче важливіший за розділ про встановлення.

Плануйте використання дискового простору, а не RAM. Gateway є процесом Python. Фактичне навантаження на сервер створює те, що запускає агент: збірка або набір тестів. Каталог стану збільшується разом з історією чату, а embedding model завантажується під час першого запуску. Тому через кілька тижнів виміряйте його розмір на власному сервері за допомогою du -sh ~/.kiro/crew, а не покладайтеся на будь-які показники, опубліковані протягом першого місяця існування проєкту.

Який із трьох способів інсталяції слід використовувати

Проєкт пропонує три способи. Однорядковий інсталятор завантажує 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 — це змінюваний тег. Він вказує на найновіший стабільний реліз, тому під час наступного завантаження версія може змінитися без вашого рішення, а сам тег не фіксує, яка саме версія використовувалася. Теги версій незмінні, тому використовуйте такий тег. Найновіший реліз станом на 6 August 2026 — 0.1.3, опублікований 5 August 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:

Запустіть контейнер, а потім перевірте 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 має позначити контейнер як справний приблизно протягом хвилини, а /api/health відповідає без токена. Так само працюють /api/live і /api/ready, завдяки чому їх можна використовувати як probes. Якщо стан залишається starting, перед будь-якими змінами прочитайте docker logs kirocrew. Під час першого запуску завантажується embedding model, тому повільне з’єднання може суттєво збільшити тривалість першого запуску.

Запускайте його через 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). Це означає, що цей unit працює правильно. Поєднання Type=oneshot і RemainAfterExit=yes тут правильне, оскільки docker compose up -d завершується одразу після запуску контейнера: systemd відстежує, що стек запущено, а не процес, який працює на передньому плані. Якщо натомість вказати Type=simple, systemd побачить, що команда одразу завершилася, позначить сервіс як зупинений, а потім або припинить спроби запуску, або ввійде в цикл перезапусків — залежно від параметра Restart=. Для нативного встановлення проєкт постачає власний еквівалент — kirocrew service install, який записує /etc/systemd/system/kirocrew.service і запускає gateway від імені вашого користувача. Не запускайте обидва unit. Розширений опис цієї теми наведено в матеріалі Сервіси та таймери systemd на VPS.

Перший запуск: увійдіть і отримайте токен dashboard

Контейнер запускає gateway, але runtime агента ще не авторизований. Увійдіть усередині контейнера:

docker exec -it kirocrew kiro-cli login

Команда виведе код пристрою та URL, який потрібно відкрити у власному браузері. Потім створіть токен dashboard:

docker exec kirocrew kirocrew token --ttl 2h

URL dashboard: http://localhost:5476/?token=<the token>. Термін дії токенів обмежений: за замовчуванням сесії тривають одну годину, а задокументований максимальний термін становить двадцять годин. Якщо dashboard завантажується порожнім або одразу повертає вас на сторінку входу, зазвичай це означає, що токен завершився. Створіть новий токен. Ніколи не вставляйте токен у ticket або повідомлення в чаті, оскільки той, хто має токен, має доступ до вашого агента.

Отримуйте доступ до dashboard через SSH і ніколи не публікуйте порт 5476

Знову подивіться на адресу bind у прикладі проєкту: -p 127.0.0.1:5476:5476. Усередині контейнера gateway прослуховує 0.0.0.0, оскільки він має бути доступним через зіставлення портів, але саме зіставлення публікує порт лише на loopback хоста. Видаліть префікс 127.0.0.1: — і gateway стане доступним у публічному інтернеті для будь-кого, хто сканує цей порт. Правило firewall також не допоможе: 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=....

Через тунель слід враховувати одну документовану особливість: gateway сприймає перенаправлені запити як віддалені, тому endpoints для запису конфігурації та розкриття секретів у dashboard відхиляють такі запити. Якщо зміна налаштувань не зберігається через 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. Він залишає dashboard усередині вашого tailnet, а не на публічному hostname. Використовуйте цей варіант замість публічного reverse proxy. Токен передається в URL, а URL записується в кожен access log на всьому шляху запиту.

Надайте агенту мінімально можливу зону ураження

Під час першого запуску контейнер перевіряє підтримку sandbox, і результат визначає, чи можуть агенти щось виконувати. Якщо ізоляція просторів імен доступна, дочірні процеси агента запускаються ізольовано. Якщо її немає і KIROCREW_ALLOW_UNSANDBOXED=1 не задано, виконання блокується, а не запускається без обмежень. Тому gateway, який виглядає справним, але всі завдання зависають, зазвичай вказує саме на цю проблему. Результат рішення зберігається в 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-монтування / і будь-який каталог із даними іншого сервісу.

Решта налаштувань визначає базові обмеження для кожного агента, якому дозволено виконувати команди. Обмежте його облікові дані одним репозиторієм або одним bucket, який йому потрібен. Ніколи не використовуйте персональний токен із правами на весь обліковий запис. Запускайте агент від імені окремого користувача, у домашньому каталозі якого немає інших даних. Саме для цього потрібні користувачі з мінімальними привілеями на VPS. Якщо агент пише код, а потім запускає його, надайте йому машину, яку можна зламати без наслідків: одноразова VM для coding agents є надійнішою межею, ніж будь-який прапорець у цьому compose-файлі, оскільки її можна видалити, а не очищати. Та сама логіка стосується безпечного запуску OpenClaw на VPS і self-hosting агента Hermes на VPS. Інструменти також збільшують зону ураження. Якщо надати агенту вебпошук, кожна отримана ним сторінка стає недовіреним введенням. Тому підключення агента до власного екземпляра SearXNG є рішенням щодо prompt injection так само, як і щодо мережевої взаємодії. Заплановані завдання також витрачають кошти, поки ви спите, оскільки інференс оплачується з вашого тарифного плану Kiro. Тому перед додаванням нічного завдання встановіть обмеження, описані в контролюванні вартості AI-агента на VPS.

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

Спочатку визначте фактичне ім’я тому. Compose додає до іменованих томів префікс із назви проєкту, яка за замовчуванням збігається з назвою каталогу. Тому том, оголошений як kirocrew-home у /opt/kirocrew/compose.yaml, створюється як kirocrew_kirocrew-home:

docker volume ls

Перед копіюванням зупиніть gateway. memory.db і memory_index.db — це бази даних SQLite. Копіювання бази даних під час запису може зберегти незавершену транзакцію, після чого відновлений файл буде пошкоджено. У власних інструкціях проєкту зазначено те саме: переміщуйте дані пам’яті лише після зупинки gateway.

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 czf потрібно вказати tar xzf:

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 завантажує образ, якщо його ще немає на сервері, тому для оновлення достатньо змінити тег. Відкат виконується так само, але із зазначенням старого номера. Ви отримаєте саме той образ, який використовувався раніше, оскільки теги версій незмінні.

Бінарний файл відкочується без проблем. Стан системи може не відкотитися. Новіший gateway може перезаписати config.json або мігрувати бази даних у пам’яті у формат, який старіший gateway не читає. Станом на August 2026 задокументованого шляху для downgrade немає. Тому якщо старий образ запускається, але працює неправильно, не витрачайте час на налагодження. Зупиніть його, відновіть резервну копію, створену перед оновленням, і запустіть знову. Саме тому резервну копію створюють спочатку. Через це звичка спочатку оновлювати, а потім створювати резервну копію, не підходить для такого молодого проєкту.

Що тут не доведено

Будьте реалістичні щодо віку цього програмного забезпечення. Версії 0.1.3 на момент написання цього матеріалу лише кілька днів. Її примітки до випуску містять автоматично сформовані посилання на журнал змін, а не нотатки щодо міграції. Даних про оновлення поки немає. Тому жоден результат у цьому посібнику не підтверджено тривалою експлуатацією. Зростання обсягу пам’яті, розмір бази даних і надійність планувальника слід вимірювати на власному сервері, а не вважати передбачуваними.

Перед тим як покладатися на ці можливості, самостійно перевірте дві ситуації. По-перше, з’ясуйте, чи читає попередня версія дані стану, записані новішою версією. Перевірте це на копії тому, доки помилка не має наслідків, а не під час простою. По-друге, перевірте, що робить gateway, коли термін дії входу в 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 volume, попередньо зупинивши шлюз. memory.db і memory_index.db — це бази даних SQLite, тому копія, створена під час запису шлюзу, може бути неузгодженою. Під час перенесення на новий хост перенесіть workspace/memory/, два файли баз даних і config.json. Файли PID, журнал подій безпеки та .env належать старому хосту.

Чи слід використовувати тег stable або тег версії?

Використовуйте тег версії. stable змінюється з кожним випуском, тому під час наступного pull версія, яку ви запускаєте, може змінитися, а сам тег не повідомляє, що саме запущено. Теги версій, наприклад 0.1.3, незмінні. Саме це дає змогу виконати rollback: поверніть старий номер і отримаєте ідентичний образ. Станом на 6 August 2026 найновіший випуск — 0.1.3.

Чому мій агент відмовляється виконувати будь-які команди?

Під час першого запуску контейнер перевіряє підтримку sandbox. Якщо контейнер не може ізолювати підпроцеси агента, а KIROCREW_ALLOW_UNSANDBOXED=1 не встановлено, він відмовляється виконувати їх замість запуску без ізоляції. Тому шлюз виглядає справним, але кожне завдання зависає. docker logs kirocrew показує рішення щодо sandbox, прийняте під час першого запуску. Після встановлення цієї змінної контейнер стає єдиною межею між агентом і хостом. Тому не монтуйте нічого, що ви не передали б агенту безпосередньо.

Чи потрібен обліковий запис Kiro для self-hosting KiroCrew?

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