Як розгорнути Rakazo на власному VPS

Що насправді запускає self-hosting Rakazo

Self-hosting Rakazo означає запуск п’яти компонентів на одному Linux-сервері: PostgreSQL, процесу Graphile Worker, API, вебзастосунку та окремого sandbox-контейнера для кожного активного бота. Rakazo — open-source альтернатива Grok Bot, опублікована elie222 за ліцензією Apache 2.0. Кожен бот отримує власний потік, власний комп’ютер, власну пам’ять і власну історію. Він також може запускати однорангових ботів або короткоживучих субагентів.

Саме тому Rakazo слід розміщувати на VPS (virtual private server), а не на настільному комп’ютері. Бот, який зберігає пам’ять і виконує заплановані завдання, має бути доступним, поки ви спите. Ноутбук, що переходить у режим сну, зупиняє обробку черги.

Станом на August 2026 Rakazo перебуває на ранній стадії beta, тому сприймайте цю конфігурацію як робочий варіант, а не як завершений appliance. Увесь стек написано на TypeScript: React 19 і Vite для вебзастосунку, Hono для API, Postgres із Prisma, Better Auth для облікових записів і Graphile Worker для фонових завдань. Graphile Worker зберігає свою чергу в Postgres, тому запускати Redis або друге сховище даних не потрібно. .env.example встановлює WAKEUP_DRIVER=graphile, тобто пробудження бота є завданням, що зберігається в Postgres. Якщо зупинити Postgres, разом із ним зупиняється виконання всіх запланованих дій ботів. Якщо ви віддаєте перевагу складанню агента з окремих компонентів замість запуску готового продукту, альтернативним варіантом буде створення власного агента з компонентів.

Чому тариф на 1 GB для цього не підійде

Порахуйте процеси. Postgres — один. API працює як процес Node. Worker — другий. Вебзастосунок — третій. Supervisor sandbox — четвертий. Крім того, кожен запущений bot отримує container із графічним робочим столом Linux і браузером.

У власній документації про розгортання проєкту наведено одну реалістичну цифру: машини з 2 vCPU і 4 GB достатньо для API, worker і Postgres, якщо E2B керує робочими столами bot. Це розмір control plane без ресурсоємної частини, яку розміщено в іншому місці. Увімкніть SANDBOX_PROVIDER=docker — і ці робочі столи перемістяться на ваш VPS, тому 4 GB стануть мінімальною межею, а не цільовим значенням. Почніть з 8 GB, якщо плануєте тримати активними більше одного bot, і вимірюйте фактичне споживання за допомогою docker stats під час роботи bot. Саме браузер у sandbox найбільше впливає на споживання пам’яті, тому за специфікацією визначити його неможливо. Загальний метод розрахунку ресурсів сервера для роботи агентів докладно описано в матеріалі скільки RAM і CPU насправді потрібно VPS для агента.

Одне налаштування не дає ситуації погіршитися. .env.example постачається з SANDBOX_IDLE_MS=600000 і коментарем про те, що після вказаної кількості мілісекунд бездіяльності він призупиняє комп’ютери E2B або зупиняє Docker-контейнери. Після 10 хвилин бездіяльності комп’ютер видаляється. Мінімальне допустиме значення — 30000. Без цього кожен bot, якого ви коли-небудь запускали, утримував би пам’ять безстроково.

Дисковий простір також має значення. Образ sandbox, модулі Node і том Postgres використовують один диск, тому 40 GB — розумний початковий обсяг.

Зафіксуйте версію до клонування

Rakazo розвивається швидко, а main не є релізом. Станом на 16 August 2026 у репозиторії є лише один tag — v0.1.0-beta, опублікований 13 August 2026 і позначений як prerelease.

git clone https://github.com/elie222/rakazo.git
cd rakazo
git checkout 53b119a68d9ef843d23aa3b7e3719b6be7b51fdb
git log -1 --format='%H %ci'

Це той commit, на який вказує v0.1.0-beta. Зафіксуйте commit, а не branch або tag. Branch зміниться під час наступного git pull, а tag є змінною міткою, яку maintainer може перенаправити, тому жоден із них не ідентифікує tree, до якого можна повернутися. Ідентифікатор commit не змінюється. Запишіть його поруч з іншими параметрами сервера, оскільки після невдалого оновлення найпростішим виправленням є git checkout <old commit> і повторна збірка. Це працює лише тоді, коли ви знаєте, який commit був робочим.

Вимоги: Node 22, pnpm 9 і Docker

node -v
pnpm -v
docker --version

package.json оголошує "engines": { "node": ">=22" } і "packageManager": "pnpm@9.15.0", тому node -v має вивести v22 або новішу версію. Пакет Node в архіві Ubuntu зазвичай старіший, тому встановіть його з NodeSource або через nvm. pnpm постачається разом із Node через corepack:

corepack enable
corepack prepare pnpm@9.15.0 --activate

Docker Engine разом із compose plugin забезпечує решту компонентів, а ваш користувач має мати доступ до daemon. Якщо docker ps повертає permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock, додайте користувача до групи docker і відкрийте нову login shell. Спочатку врахуйте наслідки: членство в групі docker рівнозначне root-доступу до машини, оскільки будь-хто з цієї групи може запустити контейнер, змонтований до файлової системи хоста.

Налаштуйте .env, потім запустіть Postgres

cp .env.example .env
chmod 600 .env

Перш ніж будь-який компонент стане доступним через мережу, потрібно змінити два значення. .env.example постачається зі значеннями BETTER_AUTH_SECRET=replace-with-32-plus-character-secret і ENCRYPTION_KEY=replace-with-64-char-hex-or-passphrase. Rakazo відхиляє ці значення-заповнювачі поза середовищем розробки, тому неповністю налаштоване розгортання одразу завершується з помилкою, а не запускається із секретом, опублікованим у репозиторії.

openssl rand -base64 48
openssl rand -hex 32

Потім окремо запустіть базу даних і виконайте міграції.

docker compose --env-file .env -f infra/compose/docker-compose.yml up postgres -d
pnpm install
pnpm db:generate
pnpm db:migrate
pnpm sandbox:build

pnpm sandbox:build збирає образ комп’ютера бота, визначений у package.json як docker build -t rakazo/computer:local infra/sandboxes/computer. Це графічний образ, тому під час першої збірки завантажується багато даних і процес триває довго. Перевірте, що образ створено, за допомогою docker image ls rakazo/computer. Команда має вивести один рядок.

Файл compose публікує Postgres на 127.0.0.1:5433:5432, доступному лише через loopback. Залиште це значення без змін. Облікові дані для середовища розробки — rakazo:rakazo. Вони містяться в репозиторії, а порт Postgres із доступним через інтернет опублікованим паролем сканери знаходять протягом кількох годин. Production-файл compose натомість читає POSTGRES_PASSWORD, тому задайте там випадковий рядок, коли перейдете до production.

Перший запуск

pnpm dev

Ця команда запускає чотири компоненти: API на порту 3100, Graphile Worker, вебзастосунок Vite на порту 5173 і supervisor sandbox на порту 7091. Застосунок доступний за адресою http://127.0.0.1:5173. Має відобразитися сторінка входу.

На VPS ви не працюєте безпосередньо на цьому комп’ютері, тому не слід публікувати порт 5173 для доступу до застосунку. Натомість перенаправте порти через SSH (secure shell) зі свого комп’ютера.

ssh -L 5173:127.0.0.1:5173 -L 3100:127.0.0.1:3100 you@your-server

Зверніть увагу на різницю між цими двома способами запуску. pnpm dev запускає Vite на хості з локальною прив’язкою. Сервіс web у compose-файлі публікує 5173:5173 на всіх інтерфейсах. Якщо запустити повний стек розробки з compose на публічному VPS, застосунок стане доступним ззовні. Тому для всього, що має працювати постійно, використовуйте production-файл і його reverse proxy.

Який sandbox provider безпечно використовувати на сервері?

Це єдине налаштування, яке потрібно виконати правильно. SANDBOX_PROVIDER у .env має чотири значення.

• docker — значення за замовчуванням. Кожен бот отримує власний container на вашій машині, створений з image pnpm sandbox:build. Це найшвидший варіант self-hosted розгортання.
• e2b запускає комп’ютери ботів у E2B і потребує E2B_API_KEY. Проєкт рекомендує цей варіант для публічних або багатокористувацьких розгортань, оскільки він відокремлює комп’ютери ботів від хоста, на якому працюють ваш API і база даних.
• desktop виконує команди бота безпосередньо на хості API та worker. В інструкції репозиторію прямо сказано: не використовуйте цей режим на публічному або спільному сервері.
• fake — це емулятор, який працює в процесі, для тестування. Це не режим виконання.

Сприймайте це попередження про desktop буквально. У desktop mode взагалі немає межі ізоляції. Тому бот виконує shell-команди від імені користувача, під яким працює API process, і має доступ до home directory цього користувача, його SSH keys, cloud credentials і його .env. Текст на вебсторінці, яку читає бот, стає командою на вашому сервері. Desktop mode на сервері — це спосіб надати боту доступ до ваших облікових даних. Використовуйте його лише на машині, за якою ви безпосередньо працюєте, або не використовуйте взагалі.

docker — це справжня межа ізоляції, але не бездоганна. Один бот не може читати файли іншого бота, оскільки кожен бот має власний container. Однак supervisor, який створює ці containers, монтує /var/run/docker.sock, а контроль над Docker socket хоста означає контроль над хостом. Тому supervisor має бути доступний лише приватно. .env.example описує SANDBOX_SUPERVISOR_TOKEN як додатковий окремий service credential, значенням якого за замовчуванням стає BETTER_AUTH_SECRET, якщо воно порожнє. Це означає, що залишення цього секрету як placeholder захищає service, який створює containers, рядком, який може прочитати будь-хто на GitHub. Установіть обидва значення. Для найкращої доступної тут ізоляції використовуйте e2b або надайте Rakazo окрему машину, на якій більше нічого немає. Саме це обґрунтовує запуск coding agents у одноразовій VM: найдешевший спосіб пережити помилкову дію агента — використовувати машину, яка не має жодної цінності.

Куди додавати API-ключі моделей?

Rakazo не має керування оплатою моделей. Ви використовуєте власний ключ. .env.example задає PI_DEFAULT_PROVIDER=openrouter, тому OPENROUTER_API_KEY є стандартним місцем, а ключі провайдерів працюють через те саме налаштування.

Зберігайте ключ у .env і не додавайте його до жодного файла, який ви комітите. Обидві команди compose у репозиторії передають --env-file .env, тому значення потрапляють у контейнери, не записуючись у YAML-файли, які відстежує git. Також можна залишити OPENROUTER_API_KEY порожнім і вставити ключ у застосунку під час початкового налаштування. Це ще одна причина, чому ENCRYPTION_KEY має містити справжнє випадкове значення, а не значення-заповнювач, з яким постачається застосунок.

Перш ніж бот почне використовувати ключ, установіть для нього ліміт витрат у провайдера. Бот, який зациклився, продовжує витрачати кошти. Ліміт для окремого ключа — єдиний спосіб зупинити такі витрати без постійного моніторингу. Призначте цьому ключу окреме ім’я, щоб за потреби відкликати лише його.

Перехід від режиму розробки до конфігурації, яку можна залишити працювати

У репозиторії є production compose-файл, який запускає Postgres, API, worker, web app і Caddy для автоматичного отримання сертифікатів TLS (transport layer security). Для bot computers потрібен E2B.

sudo DEPLOY_USER=deploy bash infra/compose/harden-host.sh
docker compose --env-file .env -f infra/compose/docker-compose.prod.yml up -d --build

harden-host.sh вимикає вхід SSH за паролем, налаштовує правила UFW (uncomplicated firewall) для SSH, HTTP і HTTPS, вмикає fail2ban і застосовує профілі AppArmor. Прочитайте його перед запуском, оскільки він змінює спосіб входу в систему. Під час виконання залиште відкритим другий сеанс SSH.

Для production .env потрібно більше, ніж для development. У self-host doc наведено цей мінімальний набір.

NODE_ENV=production
RAKAZO_HOST=app.example.com
BETTER_AUTH_URL=https://app.example.com
WEB_ORIGIN=https://app.example.com
API_URL=https://app.example.com
POSTGRES_PASSWORD=<random>
BETTER_AUTH_SECRET=<random>
ENCRYPTION_KEY=<random>
E2B_API_KEY=<your key>
OPENROUTER_API_KEY=<your key>
SANDBOX_PROVIDER=e2b
AGENT_RUNTIME=pi
DATA_DIR=/data

До першого up налаштуйте A record на сервер. Caddy запитує сертифікат для імені з RAKAZO_HOST. Запит завершується помилкою, якщо це ім’я не вказує на цей сервер або якщо порт 80 недоступний ззовні.

Також налаштуйте SIGNUP_ALLOWLIST=you@example.com. Значення SIGNUPS_ENABLED=true використовується за замовчуванням. Тому instance на публічному імені приймає реєстрації від будь-кого, хто його знайде, а кожен новий обліковий запис отримує computer. Спочатку задайте allowlist. За потреби пізніше послабте це обмеження.

Вважайте docs/self-host.md у репозиторії джерелом актуальних production settings, оскільки вони змінюються разом із кодом, а цей посібник — ні. Оскільки роботу виконує Compose, діють звичайні правила. У основах Docker Compose для VPS пояснюється, чому --env-file і named volumes стають ще важливішими, коли stack залишають без змін на місяці.

Резервні копії

Postgres і каталог data/ — це весь екземпляр.

./scripts/backup.sh
./scripts/restore.sh backups/BACKUP_TIMESTAMP

backup.sh створює дамп Postgres і архівує data/. Для сервера, від якого ви залежите, встановіть infra/compose/backup-prod.sh як /usr/local/sbin/rakazo-backup разом із таймером, який постачається з репозиторієм, щоб ротація виконувалася автоматично. Резервна копія на тому самому диску, що й база даних, не є резервною копією, тому скопіюйте її на інший сервер або носій. Потім один раз відновіть її на резервному сервері, перш ніж вона знадобиться.

Чому це не працює і що ви побачите

pnpm db:migrate не може підключитися до бази даних. Міграція повідомляє, що не може підключитися до сервера бази даних за адресою 127.0.0.1:5433. Або контейнер Postgres не запущений, або він запущений, але ще не готовий. Виконайте docker compose --env-file .env -f infra/compose/docker-compose.yml ps і перевірте, чи повідомляє сервіс postgres про стан healthy, оскільки файл compose містить для нього перевірку стану, яка запускається кожні три секунди. Контейнер, який постійно перезапускається, зазвичай означає, що том pgdata створено з іншими обліковими даними. docker compose ... down -v очищає цей том і видаляє разом із ним дані.

Порт уже зайнятий. Запуск Postgres завершується помилкою bind: address already in use, якщо інший процес використовує 5433. Найчастіше це попередній стек Rakazo, який ви забули зупинити. sudo ss -lntp | grep 5433 показує процес.

Бот ніколи не отримує комп’ютер. Якщо задано SANDBOX_PROVIDER=docker, але відсутній образ rakazo/computer:local, запускати нічого. docker image ls rakazo/computer відповідає на це одним рядком, а pnpm sandbox:build усуває проблему. Якщо supervisor не може отримати доступ до Docker socket, він також не може створювати контейнери. У повідомленні буде вказано шлях: permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock.

Довга команда переривається посеред виконання. .env.example задає SANDBOX_COMMAND_TIMEOUT_MS=300000, тому одну команду всередині комп’ютера бота буде примусово завершено через п’ять хвилин. Для повільних збірок збільште це значення, а не припускайте, що sandbox аварійно завершив роботу.

pnpm install працює непередбачувано. Спочатку перевірте node -v. У workspace оголошено >=22, а старіша версія Node завершується помилкою в коді залежності, а не повідомленням про несумісність версій.

Вхід працює локально, але не через домен. BETTER_AUTH_URL, WEB_ORIGIN і API_URL мають містити той самий public origin, що й адресний рядок, разом зі схемою. Застаріле значення http://127.0.0.1:5173 в одному з них зазвичай спричиняє проблему, через яку сеанс не зберігається.

Оновлення checkout, зафіксованого на певному коміті

В інструкції self-host для оновлення описано коротку послідовність: отримайте новий вихідний код, виконайте міграцію бази даних, перезапустіть API та worker.

./scripts/backup.sh
git fetch --all
git checkout NEW_COMMIT_SHA
pnpm install
pnpm --filter @rakazo/db migrate
docker compose --env-file .env -f infra/compose/docker-compose.prod.yml up -d --build

Спочатку створіть резервну копію. Міграції виконуються лише вперед, а beta-версія не дає гарантованого способу повернутися назад. Перед оновленням перегляньте коміти між вашим зафіксованим SHA та новим SHA. У проєкті, що перебуває на такому ранньому етапі, змінні середовища можуть перейменовувати без попередження. Відсутня змінна проявиться як сервіс, який запускається, а потім завершує роботу. Якщо ви ще вирішуєте, чи варто взагалі запускати Rakazo, у огляді self-hosted AI-агентів описано інші рішення цієї категорії та витрати на їхню роботу.

FAQ

Чи можна запустити Rakazo на VPS із 1 GB оперативної пам’яті?

Ні. Postgres, API, worker, sandbox supervisor і web app працюють одночасно, а з SANDBOX_PROVIDER=docker кожен активний bot додає container із графічним desktop і browser. У документації проєкту зазначено, що 2 vCPU і 4 GB достатньо лише для API, worker і Postgres, якщо E2B розміщує desktop середовища bot. Вважайте 4 GB мінімальним обсягом для control plane і використовуйте більше, якщо desktop середовища працюють на вашій машині.

Чи безпечний провайдер desktop sandbox на сервері?

Ні. desktop виконує команди bot безпосередньо на хості API та worker, від імені користувача, під яким працює цей процес. Файли й облікові дані цього користувача також доступні процесу. У репозиторії зазначено, що цей режим не слід використовувати на публічному або спільному сервері. Використовуйте docker для окремого container кожного bot або e2b, якщо входить більше однієї людини.

Яку версію Rakazo слід встановити?

Станом на 16 August 2026 існує один tag — v0.1.0-beta, опублікований 13 August 2026 і позначений як prerelease. Перейдіть до commit, на який він вказує, — 53b119a68d9ef843d23aa3b7e3719b6be7b51fdb, а не відстежуйте main. Гілка може змінитися, а tag можна переназначити, тому жоден із них не ідентифікує tree, до якого можна повернутися. Збережіть commit, оскільки відкат можливий лише тоді, коли відомо, яка саме версія працювала.

Де зберігати мій OpenRouter API key?

У .env як OPENROUTER_API_KEY і ніколи не додавайте його до compose file, який commit-иться. Обидві compose-команди в репозиторії передають --env-file .env, тому значення потрапляє до container без запису в YAML, який відстежується системою контролю версій. Також можна залишити це поле порожнім і вставити key у застосунок під час onboarding. Встановіть ліміт витрат для key у провайдера, оскільки bot у циклі продовжуватиме викликати model, доки щось його не зупинить.

Чи потрібні domain name і TLS?

Для всього, що виходить за межі першого тесту, так. Production compose file запускає Caddy і автоматично отримує сертифікати, а RAKAZO_HOST, BETTER_AUTH_URL, WEB_ORIGIN і API_URL мають використовувати одну й ту саму публічну HTTPS origin. Для першої перевірки domain можна не налаштовувати: запустіть pnpm dev і перенаправте порт 5173 через SSH замість його публікації.