Come eseguire Rakazo in self-hosting su un VPS

Cosa esegue realmente il self-hosting di Rakazo

Eseguire Rakazo in self-hosting significa eseguire cinque componenti su un unico server Linux: PostgreSQL, un processo Graphile Worker, l'API, l'app web e un container sandbox per ogni bot attivo. Rakazo è un'alternativa open source a Grok Bot, pubblicata da elie222 con licenza Apache 2.0. Ogni bot dispone di un thread, un computer, una memoria e una cronologia propri e può avviare bot peer o subagenti di breve durata.

È proprio quest'ultimo aspetto che rende adatto un VPS (virtual private server), non un desktop. Un bot che conserva la memoria ed esegue attività pianificate deve essere raggiungibile mentre si dorme. Quando un laptop entra in sospensione, la coda si interrompe.

Ad agosto 2026 Rakazo è ancora in fase di beta iniziale, quindi questa configurazione va considerata operativa, non un'appliance completa. Lo stack è interamente basato su TypeScript: React 19 e Vite per l'app web, Hono per l'API, Postgres con Prisma, Better Auth per gli account e Graphile Worker per i job in background. Graphile Worker memorizza la coda in Postgres, quindi non servono Redis né un secondo datastore da gestire. .env.example imposta WAKEUP_DRIVER=graphile, il che significa che il risveglio di un bot corrisponde a un job gestito da Postgres. Se si arresta Postgres, si arrestano anche tutte le azioni pianificate dei bot. Se invece si preferisce assemblare un agente partendo da singoli componenti anziché eseguire un prodotto sviluppato da altri, l'altra opzione è creare un agente personalizzato a partire dai componenti.

Perché un piano da 1 GB non è sufficiente

Conta i processi. Postgres è uno. L'API è un processo Node. Il worker è un secondo processo. L'applicazione web è un terzo. Il supervisore della sandbox è un quarto. Inoltre, ogni bot in esecuzione usa un container che contiene un desktop Linux grafico e un browser.

La documentazione self-hosted del progetto fornisce un unico dato realistico: una macchina con 2 vCPU e 4 GB è sufficiente per l'API, il worker e Postgres quando E2B gestisce i desktop dei bot. Questo valore riguarda solo il control plane, mentre la parte più onerosa è ospitata altrove. Imposta SANDBOX_PROVIDER=docker e questi desktop vengono spostati sul tuo VPS; di conseguenza, 4 GB diventano il requisito minimo, non l'obiettivo. Parti da 8 GB se prevedi di mantenere attivo più di un bot e misura il valore effettivo con docker stats mentre un bot è in esecuzione. È il browser all'interno della sandbox a determinare il consumo di memoria, quindi una scheda tecnica non può fornire una risposta precisa. Per il metodo generale di dimensionamento di una macchina per il lavoro degli agenti, quanta RAM e CPU servono realmente a un VPS per agenti illustra in dettaglio come effettuare la misurazione.

Un'impostazione impedisce che il consumo aumenti ulteriormente. .env.example include SANDBOX_IDLE_MS=600000 con il commento che sospende i computer E2B o arresta quelli Docker dopo il numero di millisecondi di inattività specificato. Dopo dieci minuti di inattività, il computer viene rimosso. Il valore minimo accettato è 30000. Senza questa impostazione, ogni bot aperto manterrebbe la memoria occupata indefinitamente.

Anche lo spazio su disco è importante. L'immagine della sandbox, i moduli Node e il volume Postgres condividono lo stesso disco, quindi 40 GB sono un punto di partenza ragionevole.

Blocca una versione prima del clone

Rakazo evolve rapidamente e main non è una release. Al 16 agosto 2026 il repository contiene esattamente un tag, v0.1.0-beta, pubblicato il 13 agosto 2026 e contrassegnato come prerelease.

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

Quel commit è quello indicato da v0.1.0-beta. Blocca il commit, non il branch o il tag. Al successivo git pull un branch può cambiare, mentre un tag è un'etichetta modificabile che un maintainer può riassegnare; quindi nessuno dei due identifica un albero a cui puoi tornare. L'identificativo di un commit non può cambiare. Annotalo insieme agli altri dati del server, perché quando un aggiornamento causa problemi la correzione più rapida consiste in git checkout <old commit> e in una ricostruzione, ma questo è possibile solo se sai quale commit funzionava.

Requisiti: Node 22, pnpm 9 e Docker

node -v
pnpm -v
docker --version

package.json dichiara "engines": { "node": ">=22" } e "packageManager": "pnpm@9.15.0", quindi node -v deve restituire v22 o una versione successiva. Il pacchetto Node nell’archivio Ubuntu è generalmente più vecchio, quindi installa NodeSource oppure nvm. pnpm è incluso in Node tramite corepack:

corepack enable
corepack prepare pnpm@9.15.0 --activate

Docker Engine e il plugin compose coprono il resto, ma l’utente deve poter accedere al demone. Se docker ps restituisce permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock, aggiungi l’utente al gruppo docker e apri una nuova shell di login. Prima comprendi le implicazioni: l’appartenenza a docker equivale ad avere accesso root sul computer, perché chiunque appartenga a quel gruppo può avviare un container che monta il filesystem dell’host.

Configura .env, quindi avvia Postgres

cp .env.example .env
chmod 600 .env

Prima di esporre qualsiasi componente sulla rete, devi modificare due valori. .env.example distribuisce BETTER_AUTH_SECRET=replace-with-32-plus-character-secret e ENCRYPTION_KEY=replace-with-64-char-hex-or-passphrase. Rakazo rifiuta questi valori segnaposto al di fuori dell'ambiente di sviluppo. In questo modo, una distribuzione configurata solo parzialmente termina con un errore esplicito invece di avviarsi usando un secret pubblicato nel repository.

openssl rand -base64 48
openssl rand -hex 32

Avvia quindi il database separatamente ed esegui le migration.

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 crea l'immagine del computer bot, definita in package.json come docker build -t rakazo/computer:local infra/sandboxes/computer. È un'immagine grafica, quindi la prima build scarica molti dati e richiede tempo. Verifica che sia stata creata con docker image ls rakazo/computer: il comando dovrebbe stampare una riga.

Il file Compose pubblica Postgres su 127.0.0.1:5433:5432, limitato al loopback. Lascialo così. Le credenziali di sviluppo sono rakazo:rakazo e si trovano nel repository. Una porta Postgres raggiungibile da Internet con una password pubblicata viene individuata dagli scanner nel giro di poche ore. Il file Compose di produzione legge invece POSTGRES_PASSWORD, quindi impostalo su una stringa casuale quando arriverai a quella fase.

La prima esecuzione

pnpm dev

Avvia quattro componenti: l'API sulla porta 3100, Graphile Worker, l'app web Vite sulla porta 5173 e il supervisore della sandbox sulla porta 7091. L'app è disponibile all'indirizzo http://127.0.0.1:5173 e dovrebbe essere visualizzata la pagina di accesso.

Su un VPS non si lavora direttamente sulla macchina e non si deve pubblicare la porta 5173 per accedere all'app. Inoltra invece le porte tramite SSH (secure shell) dal tuo computer.

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

Presta attenzione alla differenza tra i due metodi di esecuzione. pnpm dev esegue Vite sull'host, in ascolto solo localmente. Il servizio web del file Compose pubblica 5173:5173 su tutte le interfacce. Se avvii l'intero stack Compose di sviluppo su un VPS pubblico, l'app viene esposta su Internet. Per qualsiasi servizio che deve rimanere attivo, usa quindi il file di produzione e il relativo reverse proxy.

Quale provider di sandbox è sicuro su un server?

Questa è l’unica impostazione da configurare correttamente. SANDBOX_PROVIDER in .env accetta quattro valori.

• docker è il valore predefinito. Ogni bot riceve il proprio container sulla macchina, creato a partire dall’immagine prodotta da pnpm sandbox:build. È la configurazione self-hosted più rapida.
• e2b esegue i computer dei bot su E2B e richiede E2B_API_KEY. Il progetto lo consiglia per le distribuzioni pubbliche o multiutente, perché mantiene separati i computer dei bot dall’host che esegue l’API e il database.
• desktop esegue direttamente i comandi del bot sull’host dell’API e del worker. Le istruzioni del repository sono esplicite: non usarlo su un server pubblico o condiviso.
• fake è un emulatore in-process per i test. Non è destinato all’esecuzione in produzione.

Prendi alla lettera l’avviso relativo alla modalità desktop. In questa modalità non esiste alcun confine di isolamento: il bot esegue i comandi della shell con l’utente che esegue il processo API, usando la directory home, le chiavi SSH, le credenziali cloud e il .env di quell’utente. Il testo di una pagina web letta dal bot diventa un comando sul server. Usare la modalità desktop su un server è il modo in cui un bot finisce per avere accesso alle tue credenziali. Usala su una macchina davanti alla quale lavori, oppure non usarla affatto.

docker fornisce un confine reale, ma non perfetto. Un bot non può leggere i file di un altro bot, perché ciascuno dispone del proprio container. Il supervisore che crea questi container, però, monta /var/run/docker.sock, e il controllo del socket Docker dell’host equivale al controllo dell’host stesso. Mantieni quindi privato il supervisore. .env.example documenta SANDBOX_SUPERVISOR_TOKEN come una credenziale facoltativa per un servizio separato, che quando è vuota utilizza per impostazione predefinita BETTER_AUTH_SECRET. Lasciare questo secret al valore segnaposto protegge quindi il servizio che crea i container con una stringa leggibile da chiunque su GitHub. Imposta entrambi i valori. Per ottenere il massimo isolamento disponibile in questa configurazione, usa e2b oppure assegna a Rakazo una macchina che non contenga altro. È lo stesso principio alla base di eseguire gli agenti di coding in una VM usa e getta: il modo più economico per gestire un’azione errata di un agente è fare in modo che la sua macchina non abbia alcun valore.

Dove vanno le chiavi API dei modelli?

Rakazo non gestisce la fatturazione dei modelli. Devi fornire tu la chiave. .env.example imposta PI_DEFAULT_PROVIDER=openrouter, quindi OPENROUTER_API_KEY è il percorso abituale e le chiavi dei provider funzionano tramite la stessa impostazione.

Conserva la chiave in .env e non inserirla in alcun file sottoposto a commit. Entrambi i comandi compose nel repository passano --env-file .env, quindi i valori raggiungono i container senza essere mai scritti in file YAML monitorati da git. Puoi anche lasciare vuoto OPENROUTER_API_KEY e incollare una chiave nell'app durante la configurazione iniziale. Per questo ENCRYPTION_KEY deve contenere un valore realmente casuale, non il segnaposto incluso nel pacchetto.

Imposta presso il provider un limite di spesa per la chiave prima che un bot la utilizzi. Un bot che entra in un ciclo continua a generare costi, mentre un limite per chiave è l'unico blocco che non dipende dal monitoraggio manuale. Assegna a questa chiave un nome dedicato, così potrai revocarla senza intervenire sulle altre.

Passare dalla modalità di sviluppo a una configurazione da lasciare in esecuzione

Il repository include un file Compose per la produzione che avvia Postgres, l'API, il worker, l'applicazione web e Caddy per i certificati TLS (transport layer security), che Caddy richiede automaticamente. La configurazione si aspetta E2B per i computer del bot.

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 disabilita l'accesso SSH tramite password, configura le regole UFW (uncomplicated firewall) per SSH, HTTP e HTTPS, abilita fail2ban e applica i profili AppArmor. Leggilo prima di eseguirlo, perché modifica le modalità di accesso. Mantieni aperta una seconda sessione SSH mentre è in esecuzione.

In produzione, .env richiede più risorse rispetto all'ambiente di sviluppo. La documentazione per l'installazione autonoma indica questo requisito minimo.

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

Prima del primo up, configura un record A che punti al server. Caddy richiede un certificato per il nome indicato in RAKAZO_HOST. La richiesta non va a buon fine se il nome non risolve verso questo server o se la porta 80 non è raggiungibile dall'esterno.

Configura anche SIGNUP_ALLOWLIST=you@example.com. SIGNUPS_ENABLED=true è il valore predefinito. Di conseguenza, un'istanza pubblicata su un nome accessibile da Internet accetta registrazioni da chiunque la trovi e assegna un computer a ogni nuovo account. Configura prima una allowlist. Potrai renderla meno restrittiva in seguito, se necessario.

Considera docs/self-host.md nel repository come la fonte autorevole per le impostazioni di produzione, perché cambia insieme al codice, mentre questa guida no. Poiché il lavoro viene eseguito da Compose, valgono le normali regole. Le nozioni di base su Docker Compose per un VPS spiegano perché --env-file e i volumi denominati diventano ancora più importanti quando uno stack deve restare invariato per mesi.

Backup

Postgres e la directory data/ costituiscono l’intera istanza.

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

backup.sh esegue il dump di Postgres e archivia data/. Per una macchina da cui dipendi, installa infra/compose/backup-prod.sh come /usr/local/sbin/rakazo-backup usando il timer fornito dal repository, così la rotazione avviene automaticamente. Un backup che si trova sullo stesso disco del database non è un backup: copialo quindi su un altro sistema. Esegui poi un ripristino una volta, su un server di riserva, prima di averne bisogno.

Perché non funziona e cosa vedrai

pnpm db:migrate non riesce a raggiungere il database. La migrazione segnala che non riesce a raggiungere il server database all'indirizzo 127.0.0.1:5433. Il container Postgres potrebbe non essere in esecuzione oppure potrebbe essere ancora in fase di avvio. Esegui docker compose --env-file .env -f infra/compose/docker-compose.yml ps e verifica che il servizio postgres risulti in stato healthy, perché il file Compose gli assegna un health check eseguito ogni tre secondi. Un container che si riavvia continuamente indica in genere che il volume pgdata è stato creato con credenziali diverse. docker compose ... down -v lo rimuove e cancella anche i dati contenuti al suo interno.

La porta è già occupata. L'avvio di Postgres non riesce con bind: address already in use quando un altro processo utilizza la porta 5433, spesso una precedente istanza dello stack Rakazo che non è stata arrestata. sudo ss -lntp | grep 5433 identifica il processo.

Un bot non riceve mai un computer. Se sono presenti SANDBOX_PROVIDER=docker ma non l'immagine rakazo/computer:local, non c'è nulla da avviare. docker image ls rakazo/computer risponde in una riga e pnpm sandbox:build risolve il problema. Se il supervisor non riesce ad accedere al socket Docker, non può neppure creare i container; il messaggio indica il percorso: permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock.

Un comando lungo si interrompe a metà. .env.example imposta SANDBOX_COMMAND_TIMEOUT_MS=300000, quindi un singolo comando eseguito nel computer di un bot viene interrotto dopo cinque minuti. Aumenta questo valore per le build lente, invece di presumere che la sandbox si sia arrestata.

pnpm install non funziona come previsto. Controlla node -v prima di qualsiasi altra cosa. Il workspace dichiara >=22, mentre una versione precedente di Node genera un errore nel codice delle dipendenze senza indicare che il problema riguarda le versioni.

L'accesso funziona localmente ma non tramite il dominio. BETTER_AUTH_URL, WEB_ORIGIN e API_URL devono riportare tutti la stessa origine pubblica visualizzata nella barra degli indirizzi, incluso lo schema. Un valore http://127.0.0.1:5173 obsoleto presente in uno di questi elementi è di solito la causa di una sessione che non rimane attiva.

Aggiornamento di un checkout fissato

Il percorso di aggiornamento nella documentazione per l'installazione self-hosted è breve: scaricare il nuovo codice sorgente, eseguire la migrazione del database, quindi riavviare l'API e il 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

Eseguire prima un backup. Le migrazioni procedono in avanti e una versione beta non offre alcun percorso di ripristino affidabile. Leggere i commit tra lo SHA fissato e quello nuovo prima di applicarli, perché un progetto così recente può rinominare le variabili d'ambiente senza annunciarlo e una variabile mancante si manifesta come un servizio che si avvia e poi termina. Se si sta ancora valutando se Rakazo sia la soluzione giusta da eseguire, la panoramica degli agenti AI self-hosted illustra quali altre soluzioni rientrano in questa categoria e quali risorse richiede mantenerle operative.

FAQ

Posso eseguire Rakazo su un VPS da 1 GB?

No. Postgres, l'API, il worker, il supervisore della sandbox e l'app web vengono eseguiti contemporaneamente e, con SANDBOX_PROVIDER=docker, ogni bot attivo aggiunge un container che contiene un desktop grafico e un browser. La documentazione del progetto indica che 2 vCPU e 4 GB sono sufficienti per la sola API, il worker e Postgres quando E2B ospita i desktop dei bot. Considera 4 GB il minimo per il control plane e aumenta la memoria quando i desktop vengono eseguiti sulla tua macchina.

La sandbox desktop è sicura su un server?

No. desktop esegue direttamente i comandi del bot sull'host dell'API e del worker, con l'utente che esegue il processo e con accesso ai file e alle credenziali di quell'utente. Il repository specifica di non usarlo su un server pubblico o condiviso. Usa docker per un container per bot oppure e2b quando accede più di una persona.

Quale versione di Rakazo devo installare?

Al 16 agosto 2026 esiste un solo tag, v0.1.0-beta, pubblicato il 13 agosto 2026 e contrassegnato come prerelease. Esegui il checkout del commit indicato dal tag, 53b119a68d9ef843d23aa3b7e3719b6be7b51fdb, invece di seguire main. Un branch può cambiare nel tempo e un tag può essere spostato, quindi nessuno dei due identifica un albero a cui puoi tornare in modo affidabile. Registra il commit, perché il rollback è possibile solo quando sai quale versione funzionava.

Dove devo inserire la mia chiave API OpenRouter?

In .env come OPENROUTER_API_KEY e mai in un file compose di cui esegui il commit. Entrambi i comandi compose del repository passano --env-file .env, quindi il valore raggiunge i container senza essere scritto nei file YAML tracciati. Puoi anche lasciarlo vuoto e incollare la chiave nell'app durante la configurazione iniziale. Imposta un limite di spesa per la chiave presso il provider, perché un bot bloccato in un ciclo continua a chiamare il modello finché qualcosa non lo interrompe.

Mi servono un nome di dominio e TLS?

Sì, per qualsiasi utilizzo oltre il primo test. Il file compose per la produzione esegue Caddy e ottiene automaticamente i certificati; inoltre RAKAZO_HOST, BETTER_AUTH_URL, WEB_ORIGIN e API_URL devono usare tutti la stessa origine HTTPS pubblica. Per una prima verifica puoi evitare il dominio: esegui pnpm dev e inoltra la porta 5173 tramite SSH invece di pubblicarla.