Jak samodzielnie hostować Rakazo na własnym VPS

Co faktycznie uruchamia samodzielnie hostowany Rakazo

Samodzielne hostowanie Rakazo oznacza uruchomienie pięciu elementów na jednym serwerze Linux: PostgreSQL, procesu Graphile Worker, API, aplikacji webowej oraz jednego kontenera typu sandbox dla każdego aktywnego bota. Rakazo to otwartoźródłowa alternatywa dla Grok Bot, opublikowana przez elie222 na licencji Apache 2.0. Każdy bot otrzymuje własny wątek, własne środowisko obliczeniowe, pamięć oraz historię; może również tworzyć procesy potomne lub krótkotrwałe subagenty.

Ostatni punkt wyjaśnia, dlaczego rozwiązanie to powinno działać na VPS (virtual private server), a nie na komputerze stacjonarnym. Bot przechowujący pamięć i wykonujący zaplanowane zadania musi być dostępny podczas nieobecności użytkownika. Laptop przechodzący w stan uśpienia przerywa działanie kolejki.

Rakazo w sierpniu 2026 roku znajduje się w fazie wczesnej wersji beta, dlatego należy traktować to rozwiązanie jako działającą konfigurację, a nie gotowe urządzenie. Cały stos technologiczny opiera się na TypeScript: React 19 i Vite dla aplikacji webowej, Hono dla API, Postgres z Prisma, Better Auth do obsługi kont oraz Graphile Worker do zadań w tle. Graphile Worker przechowuje kolejkę wewnątrz Postgres, więc nie ma potrzeby uruchamiania Redis ani żadnego dodatkowego magazynu danych. .env.example ustawia WAKEUP_DRIVER=graphile, co oznacza, że wybudzenie bota jest zadaniem obsługiwanym przez Postgres. Zatrzymanie Postgres powoduje zatrzymanie wszystkich zaplanowanych działań botów. Jeśli zamiast uruchamiania gotowego produktu wolisz samodzielnie złożyć agenta z poszczególnych części, alternatywną drogą jest budowa własnego agenta z komponentów.

Dlaczego plan 1 GB nie wystarczy

Należy policzyć procesy. Postgres to jeden z nich. API to proces Node. Worker to drugi. Aplikacja webowa to trzeci. Nadzorca sandboxa to czwarty. Następnie każdy uruchomiony bot otrzymuje kontener zawierający graficzny pulpit Linux oraz przeglądarkę.

Dokumentacja self-host tego projektu podaje jedną uczciwą wartość: maszyna z 2 vCPU i 4 GB RAM wystarcza dla API, workera i Postgresa, gdy E2B obsługuje pulpity botów. Jest to wartość wymagana wyłącznie dla płaszczyzny sterowania, podczas gdy najbardziej obciążające elementy są hostowane zewnętrznie. Ustawienie SANDBOX_PROVIDER=docker powoduje przeniesienie tych pulpitów na Twój VPS, przez co 4 GB staje się wartością minimalną, a nie docelową. Zacznij od 8 GB, jeśli planujesz utrzymywać aktywnego więcej niż jednego bota, i zmierz rzeczywiste zużycie za pomocą docker stats w trakcie pracy bota. To przeglądarka wewnątrz sandboxa powoduje największe zużycie pamięci, więc specyfikacja techniczna tego nie wykaże. Ogólna metoda doboru rozmiaru serwera dla pracy agentów została szczegółowo opisana w ile pamięci RAM i CPU faktycznie potrzebuje VPS dla agenta.

Jedno ustawienie zapobiega pogorszeniu sytuacji. .env.example jest dostarczane z SANDBOX_IDLE_MS=600000 wraz z komentarzem, że wstrzymuje ono komputery E2B lub zatrzymuje te oparte na Dockerze po określonej liczbie milisekund bezczynności. Po dziesięciu minutach bezczynności komputer jest usuwany. Minimalna akceptowana wartość to 30000. Bez tego każdy uruchomiony bot zajmowałby pamięć w nieskończoność.

Znaczenie ma również dysk. Obraz sandboxa, moduły Node oraz wolumen Postgres współdzielą jeden dysk, dlatego 40 GB jest rozsądnym punktem wyjścia.

Przypnij wersję przed klonowaniem

Rakazo rozwija się szybko, a main nie jest wydaniem stabilnym. Według stanu na 16 sierpnia 2026 r. repozytorium zawiera dokładnie jeden tag, v0.1.0-beta, opublikowany 13 sierpnia 2026 r. i oznaczony jako wersja przedpremierowa.

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

Ten commit jest punktem, na który wskazuje v0.1.0-beta. Należy przypiąć commit, a nie branch lub tag. Branch zmienia się przy kolejnym git pull, a tag jest etykietą, którą opiekun projektu może przenieść, więc żadne z nich nie identyfikuje jednoznacznie drzewa plików, do którego można wrócić. Identyfikator commita jest niezmienny. Zapisz swój identyfikator obok innych danych konfiguracyjnych serwera, ponieważ gdy aktualizacja spowoduje awarię, najszybszym rozwiązaniem jest git checkout <old commit> i przebudowa, co zadziała tylko wtedy, gdy wiadomo, który commit był sprawny.

Wymagania: Node 22, pnpm 9 oraz Docker

node -v
pnpm -v
docker --version

package.json deklaruje "engines": { "node": ">=22" } oraz "packageManager": "pnpm@9.15.0", dlatego node -v musi wyświetlać v22 lub wyższą wersję. Pakiet Node w repozytoriach Ubuntu jest zazwyczaj starszy, dlatego należy przeprowadzić instalację z NodeSource lub użyć nvm. Narzędzie pnpm jest dostarczane wraz z Node za pośrednictwem corepack:

corepack enable
corepack prepare pnpm@9.15.0 --activate

Docker Engine wraz z wtyczką compose zapewnia pozostałe funkcjonalności, a użytkownik musi mieć możliwość komunikacji z daemonem. Jeśli docker ps zwraca permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock, należy dodać użytkownika do grupy docker i otworzyć nową sesję powłoki. Należy pamiętać o konsekwencjach: członkostwo w docker jest równoważne z uprawnieniami root w systemie, ponieważ każdy członek tej grupy może uruchomić kontener montujący system plików hosta.

Konfiguracja pliku .env i uruchomienie Postgres

cp .env.example .env
chmod 600 .env

Przed wystawieniem jakiejkolwiek usługi na zewnątrz należy zmienić dwie wartości. .env.example dostarcza BETTER_AUTH_SECRET=replace-with-32-plus-character-secret oraz ENCRYPTION_KEY=replace-with-64-char-hex-or-passphrase. Rakazo odrzuca te wartości zastępcze poza środowiskiem programistycznym, dlatego nieprawidłowo skonfigurowane wdrożenie kończy się błędem zamiast uruchomienia z użyciem domyślnego sekretu opublikowanego w repozytorium.

openssl rand -base64 48
openssl rand -hex 32

Następnie należy uruchomić bazę danych i wykonać migracje.

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 buduje obraz komputera bota, zdefiniowany w package.json jako docker build -t rakazo/computer:local infra/sandboxes/computer. Jest to obraz graficzny, więc pierwsze budowanie pobiera dużą ilość danych i zajmuje czas. Należy potwierdzić jego obecność za pomocą docker image ls rakazo/computer, co powinno wyświetlić jeden wiersz.

Plik compose udostępnia Postgres jako 127.0.0.1:5433:5432, co ogranicza dostęp wyłącznie do interfejsu loopback. Należy pozostawić to ustawienie bez zmian. Poświadczenia programistyczne to rakazo:rakazo; znajdują się one w repozytorium, a port Postgres dostępny z Internetu z opublikowanym hasłem jest wykrywany przez skanery w ciągu kilku godzin. Produkcyjny plik compose odczytuje zamiast tego POSTGRES_PASSWORD, więc po przejściu do tego etapu należy ustawić tam losowy ciąg znaków.

Pierwsze uruchomienie

pnpm dev

Polecenie to uruchamia cztery elementy: API na porcie 3100, Graphile Worker, aplikację webową Vite na porcie 5173 oraz nadzorcę sandboxa na porcie 7091. Aplikacja jest dostępna pod adresem http://127.0.0.1:5173; powinna wyświetlić się strona logowania.

W przypadku VPS użytkownik nie ma bezpośredniego dostępu do maszyny, dlatego nie należy udostępniać portu 5173 publicznie. Zamiast tego należy przekierować porty przez SSH (secure shell) z własnego komputera.

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

Należy zachować ostrożność, rozróżniając dwa sposoby uruchamiania. pnpm dev uruchamia Vite na hoście, z powiązaniem lokalnym. Usługa web w pliku compose publikuje 5173:5173 na wszystkich interfejsach. Uruchomienie pełnego stosu deweloperskiego compose na publicznym VPS spowoduje wystawienie aplikacji na zewnątrz, dlatego do wszelkich usług działających w tle należy używać pliku produkcyjnego oraz skonfigurowanego dla niego reverse proxy.

Który dostawca środowiska izolowanego (sandbox) jest bezpieczny na serwerze?

To ustawienie jest kluczowe dla bezpieczeństwa. SANDBOX_PROVIDER w .env przyjmuje cztery wartości.

• docker to ustawienie domyślne. Każdy bot otrzymuje własny kontener na maszynie, zbudowany z obrazu wygenerowanego przez pnpm sandbox:build. Jest to najszybsza konfiguracja typu self-hosted.
• e2b uruchamia komputery botów w usłudze E2B i wymaga E2B_API_KEY. Projekt zaleca to rozwiązanie w przypadku wdrożeń publicznych lub wieloużytkownikowych, ponieważ izoluje komputery botów od hosta, na którym działa API i baza danych.
• desktop uruchamia polecenia bota bezpośrednio na hoście API i workerze. Instrukcja w repozytorium jest jednoznaczna: nie należy używać tego trybu na serwerze publicznym lub współdzielonym.
• fake to emulator wewnątrzprocesowy przeznaczony do testów. Nie jest to środowisko uruchomieniowe.

Ostrzeżenie dotyczące trybu desktop należy traktować dosłownie. W trybie desktop nie istnieje żadna granica izolacji, więc bot wykonuje polecenia powłoki jako użytkownik uruchamiający proces API, mając dostęp do jego katalogu domowego, kluczy SSH, poświadczeń chmurowych oraz .env tego użytkownika. Tekst na stronie internetowej odczytany przez bota staje się poleceniem wykonywanym na serwerze. Użycie trybu desktop na serwerze prowadzi do przejęcia poświadczeń przez bota. Należy go używać wyłącznie na maszynie, przy której się pracuje, lub zrezygnować z niego całkowicie.

docker stanowi realną, choć niedoskonałą barierę. Jeden bot nie może odczytać plików innego bota, ponieważ każdy z nich posiada własny kontener. Jednak nadzorca tworzący te kontenery montuje /var/run/docker.sock, a kontrola nad gniazdem Docker hosta oznacza kontrolę nad całym hostem. Dlatego nadzorca musi pozostać prywatny. .env.example dokumentuje SANDBOX_SUPERVISOR_TOKEN jako opcjonalne, oddzielne poświadczenie usługi, które domyślnie przyjmuje wartość BETTER_AUTH_SECRET, jeśli pozostanie puste. Oznacza to, że pozostawienie tego sekretu w postaci domyślnego symbolu zastępczego chroni usługę tworzącą kontenery ciągiem znaków, który każdy może odczytać w serwisie GitHub. Należy ustawić obie wartości. Aby uzyskać najsilniejszą dostępną separację, należy użyć e2b lub udostępnić usłudze Rakazo maszynę, na której nie znajdują się żadne inne dane. Jest to ta sama logika, która stoi za uruchamianiem agentów programistycznych w jednorazowych maszynach wirtualnych: najtańszym sposobem na przetrwanie błędu agenta jest posiadanie maszyny, która nie ma żadnej wartości.

Gdzie umieścić klucze API modeli?

Rakazo nie posiada zarządzanego systemu rozliczeń za modele. Klucz należy dostarczyć we własnym zakresie. .env.example ustawia PI_DEFAULT_PROVIDER=openrouter, dlatego OPENROUTER_API_KEY jest standardowym miejscem, a klucze dostawców działają w oparciu o to samo ustawienie.

Klucz należy przechowywać w .env i nie umieszczać go w żadnym pliku podlegającym kontroli wersji. Oba polecenia compose w repozytorium przekazują --env-file .env, dzięki czemu wartości trafiają do kontenerów bez konieczności zapisywania ich w plikach YAML śledzonych przez git. Można również pozostawić OPENROUTER_API_KEY puste i wkleić klucz w aplikacji podczas procesu konfiguracji początkowej, co stanowi kolejny powód, dla którego ENCRYPTION_KEY musi posiadać rzeczywistą losową wartość, a nie domyślny symbol zastępczy.

Przed uruchomieniem bota należy ustawić limit wydatków dla klucza w panelu dostawcy. Bot, który wpadnie w pętlę, generuje koszty, a limit przypisany do klucza jest jedynym zabezpieczeniem, które nie wymaga stałego nadzoru. Należy nadać temu kluczowi unikalną nazwę, aby w razie potrzeby można było go unieważnić niezależnie od innych.

Przejście z trybu deweloperskiego na środowisko produkcyjne

Repozytorium zawiera produkcyjny plik compose, który uruchamia Postgres, API, worker, aplikację webową oraz Caddy w celu automatycznego uzyskiwania certyfikatów TLS (transport layer security). Wymaga on E2B dla komputerów botów.

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 wyłącza logowanie przez SSH hasłem, ustawia reguły UFW (uncomplicated firewall) dla SSH, HTTP i HTTPS, włącza fail2ban oraz stosuje profile AppArmor. Należy zapoznać się z jego treścią przed uruchomieniem, ponieważ zmienia on sposób logowania. Podczas wykonywania skryptu należy pozostawić otwartą drugą sesję SSH.

Produkcyjna wersja .env wymaga więcej zasobów niż wersja deweloperska. Dokumentacja self-host zawiera listę wymagań minimalnych.

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

Przed pierwszym uruchomieniem up należy skierować rekord A na serwer. Caddy wysyła żądanie o certyfikat dla nazwy zdefiniowanej w RAKAZO_HOST, a żądanie to kończy się niepowodzeniem, jeśli nazwa nie wskazuje na ten serwer lub jeśli port 80 jest zamknięty dla ruchu z zewnątrz.

Należy również ustawić SIGNUP_ALLOWLIST=you@example.com. SIGNUPS_ENABLED=true jest wartością domyślną, co oznacza, że instancja pod publiczną nazwą akceptuje rejestracje od każdego użytkownika, a każde nowe konto otrzymuje komputer. Zaleca się najpierw skonfigurować listę dozwolonych (allowlist), a w razie potrzeby złagodzić te ustawienia w późniejszym czasie.

Należy traktować docs/self-host.md w repozytorium jako wiarygodne źródło ustawień produkcyjnych, ponieważ zmieniają się one wraz z kodem, w przeciwieństwie do niniejszego przewodnika. Ponieważ za działanie odpowiada Compose, mają zastosowanie standardowe zasady, a podstawy Docker Compose dla VPS wyjaśniają, dlaczego --env-file oraz nazwane wolumeny zyskują na znaczeniu, gdy stos usług ma działać bez nadzoru przez wiele miesięcy.

Kopie zapasowe

Baza danych Postgres oraz katalog data/ stanowią pełną instancję.

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

Narzędzie backup.sh wykonuje zrzuty bazy Postgres i archiwizuje data/. W przypadku maszyny o znaczeniu krytycznym należy zainstalować infra/compose/backup-prod.sh jako /usr/local/sbin/rakazo-backup wraz z timerem dostarczonym w repozytorium, co pozwoli na automatyczną rotację kopii. Kopia zapasowa przechowywana na tym samym dysku co baza danych nie jest kopią zapasową, dlatego należy ją skopiować poza serwer. Przed wystąpieniem awarii należy przynajmniej raz przeprowadzić procedurę przywracania danych na zapasowym serwerze.

Dlaczego występuje błąd i co zobaczysz

pnpm db:migrate nie może połączyć się z bazą danych. Migracja zgłasza brak możliwości połączenia z serwerem bazy danych pod adresem 127.0.0.1:5433. Kontener Postgres nie został uruchomiony lub jest w trakcie inicjalizacji. Uruchom docker compose --env-file .env -f infra/compose/docker-compose.yml ps i sprawdź, czy usługa postgres zgłasza stan healthy; plik compose zawiera test kondycji (health check) wykonywany co trzy sekundy. Kontener restartujący się w pętli zazwyczaj oznacza, że wolumen pgdata został utworzony z innymi danymi uwierzytelniającymi. Polecenie docker compose ... down -v czyści go, usuwając przy tym dane.

Port jest już zajęty. Uruchomienie Postgres kończy się błędem bind: address already in use, gdy inny proces zajmuje port 5433; najczęściej jest to wcześniejsza instancja Rakazo, której nie zatrzymano. Polecenie sudo ss -lntp | grep 5433 wskazuje nazwę tego procesu.

Bot nie otrzymuje komputera. Przy użyciu SANDBOX_PROVIDER=docker i braku obrazu rakazo/computer:local nie ma co uruchomić. Polecenie docker image ls rakazo/computer odpowiada na to w jednej linii, a pnpm sandbox:build naprawia problem. Jeśli supervisor nie może połączyć się z gniazdem Docker, nie może również tworzyć kontenerów, a komunikat wskazuje ścieżkę: permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock.

Długie polecenie przerywa działanie. .env.example ustawia SANDBOX_COMMAND_TIMEOUT_MS=300000, więc pojedyncze polecenie wewnątrz komputera bota zostaje przerwane po pięciu minutach. Zwiększ tę wartość dla powolnych kompilacji, zamiast zakładać awarię środowiska izolowanego (sandbox).

pnpm install działa nieprawidłowo w niejasny sposób. Przed podjęciem innych działań sprawdź node -v. Środowisko robocze deklaruje >=22, a starsza wersja Node zgłasza błędy w kodzie zależności zamiast komunikatu o niezgodności wersji.

Logowanie działa lokalnie, ale nie przez domenę. BETTER_AUTH_URL, WEB_ORIGIN oraz API_URL muszą zawierać ten sam publiczny origin, co pasek adresu, włącznie ze schematem. Pozostałość http://127.0.0.1:5173 w jednym z nich jest najczęstszą przyczyną sesji, która nie zostaje utrzymana.

Aktualizacja przypiętej wersji (pinned checkout)

Ścieżka aktualizacji w dokumentacji self-host jest krótka: pobierz nowe źródła, wykonaj migrację bazy danych, zrestartuj API oraz proces 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

Najpierw wykonaj kopię zapasową. Migracje są jednokierunkowe, a wersja beta nie oferuje niezawodnej ścieżki powrotnej. Przed aktualizacją przejrzyj commity między obecnie przypiętym SHA a nowym. Tak młody projekt często zmienia nazwy zmiennych środowiskowych bez wcześniejszego powiadomienia. Brakująca zmienna powoduje, że usługa uruchamia się, a następnie natychmiast kończy działanie. Jeśli nadal rozważasz, czy Rakazo jest właściwym rozwiązaniem, zestawienie samodzielnie hostowanych agentów AI omawia inne dostępne opcje w tej kategorii oraz koszty ich utrzymania.

FAQ

Czy mogę uruchomić Rakazo na VPS z 1 GB pamięci RAM?

Nie. Postgres, API, worker, sandbox supervisor oraz aplikacja webowa działają jednocześnie, a przy użyciu SANDBOX_PROVIDER=docker każdy aktywny bot uruchamia kontener z graficznym pulpitem i przeglądarką. Dokumentacja projektu wskazuje, że 2 vCPU i 4 GB RAM wystarczają dla API, workera i Postgresa tylko wtedy, gdy E2B obsługuje pulpity botów zewnętrznie. Należy przyjąć 4 GB jako wartość minimalną dla płaszczyzny sterowania i zwiększyć zasoby, jeśli pulpity działają na własnym serwerze.

Czy dostawca sandboxa pulpitu jest bezpieczny na serwerze?

Nie. desktop wykonuje polecenia bota bezpośrednio na hoście API i workera, z uprawnieniami użytkownika uruchamiającego proces, co daje dostęp do plików i poświadczeń tego użytkownika. Repozytorium odradza stosowanie tego rozwiązania na serwerach publicznych lub współdzielonych. Należy użyć docker w celu izolacji każdego bota w osobnym kontenerze lub e2b, gdy z systemu korzysta więcej niż jedna osoba.

Którą wersję Rakazo należy zainstalować?

Na dzień 16 sierpnia 2026 dostępny jest jeden tag, v0.1.0-beta, opublikowany 13 sierpnia 2026 i oznaczony jako wersja przedpremierowa. Należy sprawdzić commit, na który wskazuje ten tag, 53b119a68d9ef843d23aa3b7e3719b6be7b51fdb, zamiast śledzić gałąź main. Gałąź może ulec zmianie, a tag może zostać przeniesiony, więc żadne z nich nie gwarantuje możliwości powrotu do konkretnego stanu drzewa plików. Należy zapisać identyfikator commita, ponieważ wycofanie zmian jest możliwe tylko przy znajomości działającej wersji.

Gdzie umieścić klucz API OpenRouter?

W pliku .env jako zmienną OPENROUTER_API_KEY; nigdy nie należy umieszczać go w pliku compose, który jest dodawany do repozytorium. Oba polecenia compose w repozytorium przekazują --env-file .env, dzięki czemu wartość trafia do kontenerów bez zapisywania jej w śledzonym pliku YAML. Można również pozostawić to pole puste i wkleić klucz w aplikacji podczas konfiguracji wstępnej. Należy ustawić limit wydatków dla klucza u dostawcy, ponieważ bot w pętli będzie wywoływał model do momentu przerwania procesu.

Czy wymagana jest nazwa domeny i TLS?

W przypadku każdego zastosowania wykraczającego poza pierwsze testy – tak. Produkcyjny plik compose uruchamia Caddy i automatycznie pobiera certyfikaty, a RAKAZO_HOST, BETTER_AUTH_URL, WEB_ORIGIN oraz API_URL muszą korzystać z tego samego publicznego źródła HTTPS. Do pierwszych testów można pominąć domenę: należy uruchomić pnpm dev i przekierować port 5173 przez SSH zamiast udostępniać go publicznie.