Rakazo self-host: bot AI su un VPS con Docker

Cosa esegue realmente Rakazo in self-hosting

Eseguire Rakazo in self-hosting significa eseguire cinque componenti su un unico server Linux: PostgreSQL, un processo Graphile Worker, l'API, l'applicazione web e un container sandbox che funge da computer dei bot. Rakazo è un'alternativa open source a Grok Bot, pubblicata da elie222 con licenza Apache 2.0. Ogni bot ha conversazioni, memoria, routine e cronologia proprie, usa lo stesso Team Computer degli altri bot del workspace, a meno che non gli venga assegnato un Private Computer, e può avviare bot omologhi o subagent di breve durata. Se termini come memoria, subagent e chiamata a uno strumento hanno un significato poco chiaro in questa frase, vale la pena dedicare prima un pomeriggio a un percorso graduale per capire come funzionano realmente gli agenti, perché la maggior parte delle impostazioni riportate di seguito ha senso solo quando riesci a visualizzare cosa fa un bot quando si attiva.

È proprio per questo che Rakazo va eseguito su un VPS (virtual private server), non su un computer desktop. Un bot che conserva memoria ed esegue attività pianificate deve essere raggiungibile mentre dormi. Quando un laptop entra in sospensione, la coda si interrompe.

A ottobre 2026 Rakazo si definisce ancora in versione beta, anche se ora pubblica release con numerazione stabile. Considera quindi questa configurazione come un'installazione operativa, non come un'appliance finita. Lo stack è interamente basato su TypeScript: React 19 e Vite per l'applicazione 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 archivio dati da gestire. .env.example imposta WAKEUP_DRIVER=graphile, quindi l'attivazione di un bot corrisponde a un job gestito da Postgres. Se arresti Postgres, si arrestano anche tutte le attività pianificate dei bot. Se preferisci assemblare un agente partendo dai singoli componenti invece di eseguire un prodotto sviluppato da altri, l'alternativa è costruire un agente dai suoi componenti.

Perché un piano da 1 GB non è sufficiente

Contate i processi. Postgres è uno. L'API è un processo Node. Il worker è un secondo processo. L'app web è un terzo. Il supervisore della sandbox è un quarto. Poi ci sono i computer dei bot: per impostazione predefinita, un unico container Team Computer condiviso che contiene un desktop Linux grafico, con un display X separato e un processo Chrome per ogni bot attivo.

La documentazione self-host del progetto non indica più le dimensioni dell'host. La versione beta di agosto 2026 indicava come sufficiente una macchina con 2 vCPU e 4 GB per l'API, il worker e Postgres quando E2B gestisce i desktop dei bot. La documentazione in v0.3.1, verificata il 21 ottobre 2026, elenca soltanto i requisiti software. Indica però un limite per computer: con le sandbox Docker, RAKAZO_COMPUTER_MEMORY ha come valore predefinito 2g e RAKAZO_COMPUTER_CPUS ha come valore predefinito 2. Questo limite si applica a ogni computer, non a ogni bot. Ogni workspace riceve un Team Computer per impostazione predefinita e ogni bot Team attivo esegue il proprio desktop e browser al suo interno, quindi tutti condividono quei 2 GB e quei due core. Solo un bot spostato su un Private Computer riceve un container e un limite propri. Impostate SANDBOX_PROVIDER=docker e questi desktop verranno eseguiti sul vostro VPS, oltre al control plane, quindi 4 GB rappresentano il minimo e non una dimensione obiettivo. Partite da 8 GB se prevedete di mantenere attivo più di un bot, aumentate RAKAZO_COMPUTER_MEMORY in modo che il computer condiviso possa utilizzare effettivamente quella memoria e misurate il valore reale con docker stats mentre i bot lavorano. È il browser all'interno della sandbox a determinare l'utilizzo di memoria, quindi una scheda tecnica non è sufficiente. Per impedire che una macchina di piccole dimensioni esegua troppi browser contemporaneamente, impostate un valore positivo per SANDBOX_TEAM_SCREEN_LIMIT, che limita i desktop attivi su un Docker Team Computer. Il valore distribuito 0 non impone alcun limite. Se la memoria disponibile è complessivamente ridotta, RAKAZO_COMPUTER_MEMORY accetta anche un valore inferiore, ad esempio 1536m. Per il metodo generale di dimensionamento di una macchina destinata al lavoro degli agenti, quanta RAM e CPU servono realmente a un VPS per agenti descrive in dettaglio la procedura di misurazione.

Un'impostazione impedisce che la situazione peggiori. .env.example viene distribuito con il valore SANDBOX_IDLE_MS=600000 e il relativo commento indica che i computer vengono messi in pausa o arrestati dopo quel numero di millisecondi di inattività. Dopo dieci minuti di inattività, il computer viene arrestato. Il valore minimo accettato è 30000 e 0 disabilita la sospensione per inattività. Lo stesso commento suggerisce 0 per i self-host Docker, dove un computer inattivo non ha costi, così le applicazioni e le sessioni di lunga durata restano attive. Questo vale per i costi, non per la memoria. Su un VPS di piccole dimensioni, mantenete attivo il timer, perché senza di esso ogni computer avviato e ogni browser al suo interno continuerebbero a essere eseguiti.

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

Blocca una versione prima del clone

Rakazo avanza rapidamente e main non è una release. Al 21 ottobre 2026 il repository contiene 12 tag. v0.1.0-beta, pubblicata il 13 agosto 2026, è ancora contrassegnata come prerelease. Dopo questa sono stati pubblicati dieci tag di versione stabili: v0.1.0 e v0.1.6 tra il 3 e l’8 settembre 2026, v0.2.0 il 10 ottobre 2026, quindi v0.3.0 e v0.3.1 il 19 ottobre 2026. v0.3.0 esiste solo come tag, v0.3.1 è la release contrassegnata come Latest e il dodicesimo tag, android, appartiene all’app Android e non al server.

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

Quel commit è quello a cui punta v0.3.1. Blocca il commit, non il branch o il tag. Un branch cambia al successivo git pull e un tag è un’etichetta modificabile che un maintainer può spostare. Nessuno dei due identifica quindi un tree al quale puoi tornare. Un identificatore di commit non può cambiare. Annotalo insieme agli altri dati del server, perché quando un upgrade causa problemi la correzione più rapida consiste nel git checkout <old commit> e nella ricostruzione. Questa procedura funziona solo se sai quale commit era funzionante. Rakazo è ancora definito beta, quindi vale la pena bloccare con precisione questa versione. Un progetto con una lunga cronologia di release deliberate può essere mantenuto invece su un tag pubblicato, come nel caso di uno stack self-hosted più piccolo come openGym.

Requisiti: Node 22, pnpm 9 e Docker

node -v
pnpm -v
docker --version

package.json dichiara "engines": { "node": "^22.22.2 || ^24.0.0 || >=26.0.0" } e "packageManager": "pnpm@9.15.0". Di conseguenza, node -v deve restituire v22.22.2 o una versione 22.x successiva, qualsiasi v24 oppure v26 e successive. Un v22 precedente a 22.22.2 non rientra nell'intervallo supportato e il README specifica chiaramente che Node.js 23.x e 25.x non sono supportati. Il pacchetto Node disponibile nell'archivio Ubuntu è in genere più vecchio, quindi installa NodeSource o nvm. pnpm viene fornito con Node tramite corepack:

corepack enable
corepack prepare pnpm@9.15.0 --activate

Docker Engine e il plugin compose coprono i requisiti restanti. La documentazione per il self-hosting richiede Docker Engine 26 o versione successiva e API 1.45 o versione successiva per i sottopercorsi dei volumi della home del bot, oltre a curl e OpenSSL. Anche il tuo utente deve poter accedere al daemon. Se docker ps restituisce permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock, aggiungi il tuo utente al gruppo docker e apri una nuova shell di login. Prima, considera cosa comporta questa autorizzazione: appartenere al gruppo 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

È necessario modificare diversi valori prima di avviare qualsiasi componente. .env.example include BETTER_AUTH_SECRET=replace-with-32-plus-character-secret, ENCRYPTION_KEY=replace-with-64-random-hex-characters, SCREEN_PROXY_SECRET=replace-with-32-plus-character-screen-proxy-secret e SANDBOX_SUPERVISOR_TOKEN=replace-with-32-plus-character-supervisor-token e lascia vuoto POSTGRES_PASSWORD. Tutti questi segnaposto sono pubblicati nel repository. Un deploy che ne mantiene anche solo uno usa quindi un secret leggibile da chiunque. Assegna a ciascuno un valore casuale distinto. ENCRYPTION_KEY deve contenere 64 caratteri esadecimali casuali, esattamente quelli stampati da openssl rand -hex 32. Gli altri secret richiedono almeno 32 caratteri; esegui quindi una volta per ciascuno la riga con base64. Per POSTGRES_PASSWORD la documentazione self-host richiede un valore compatibile con gli URL; te lo fornisce l'ultima riga. In v0.3.1 la stessa password viene inserita in DATABASE_URL, che include postgres://rakazo:REPLACE_WITH_POSTGRES_PASSWORD@127.0.0.1:5433/rakazo. I commit su main successivi a v0.3.1 separano questi due valori: la stringa del proprietario viene spostata in DATABASE_MIGRATION_URL e DATABASE_URL diventa postgres://rakazo_app:REPLACE_WITH_POSTGRES_APP_PASSWORD@127.0.0.1:5433/rakazo, un account di accesso separato senza privilegi di superuser, soggetto alla sicurezza a livello di riga e con il proprio POSTGRES_APP_PASSWORD. Quando sposti il pin oltre v0.3.1, prevedi di impostare anche questa seconda password.

openssl rand -base64 48
openssl rand -hex 32
openssl rand -hex 24

Avvia quindi solo il database ed esegui le migrazioni.

docker compose --env-file .env -f infra/compose/docker-compose.yml -f infra/compose/docker-compose.postgres-host.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 compilazione 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 di base non pubblica alcuna porta di Postgres. L'overlay docker-compose.postgres-host.yml usato in quel comando lo pubblica come 127.0.0.1:5433, accessibile solo tramite loopback, consentendo agli strumenti sul sistema host, come pnpm db:migrate e pnpm dev, di raggiungerlo. Lascialo configurato in questo modo. Compose non avvia Postgres senza un POSTGRES_PASSWORD in .env, ma una porta di Postgres raggiungibile da Internet viene individuata dagli scanner entro poche ore, indipendentemente dalla password. Il file Compose per la produzione legge la stessa variabile e non pubblica alcuna porta del database.

La prima esecuzione

pnpm dev

Questo comando 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'applicazione è disponibile all'indirizzo http://127.0.0.1:5173 e dovrebbe essere visualizzata una pagina di accesso.

Su un VPS non si lavora direttamente dalla macchina che esegue i servizi e non è consigliabile pubblicare la porta 5173 per raggiungerli. Inoltra invece le porte tramite SSH (secure shell) dalla tua macchina.

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

Presta attenzione alla differenza tra le modalità di esecuzione. pnpm dev esegue Vite sull'host, in ascolto solo localmente. Il file Compose per lo sviluppo pubblica 127.0.0.1:5173:5173 tramite il servizio web e 127.0.0.1:3100:3100 tramite il servizio api, entrambi solo sull'interfaccia loopback, quindi lo stesso tunnel funziona anche in questo caso. Nel file per la produzione, l'app web è esposta solo sulla rete interna e Caddy pubblica direttamente le porte 80 e 443. Usa quindi il file per la produzione e il relativo reverse proxy per qualsiasi servizio che lasci in esecuzione.

Quale provider di sandbox è sicuro su un server?

Questa è l’unica impostazione da configurare correttamente. SANDBOX_PROVIDER in .env è docker per impostazione predefinita e la documentazione self-host elenca otto valori.

• docker è il valore predefinito. I computer dei bot vengono eseguiti come container sul server, creati dall’immagine pnpm sandbox:build e avviati sotto il controllo di un supervisore. Per impostazione predefinita, i bot di uno workspace condividono un unico Team Computer; un bot riceve un container dedicato soltanto su un Private Computer. Non è necessario un account E2B.
• e2b esegue i computer dei bot su E2B e richiede E2B_API_KEY. La documentazione self-host lo indica come adatto agli ambienti di produzione pubblici o multiutente, perché mantiene i computer dei bot separati dall’host che esegue l’API e il database.
• daytona, createos e box sono altri provider remoti, ciascuno con una propria chiave: DAYTONA_API_KEY, CREATEOS_SANDBOX_API_KEY o BOX_API_KEY.
• desktop esegue direttamente i comandi del bot sull’host dell’API e dei worker, come specifica la documentazione. Non abilitarlo su un servizio pubblico o condiviso.
• fake è un emulatore destinato esclusivamente alla verifica. Non è un ambiente di runtime.
• none avvia il prodotto senza alcun computer host.

Consideralo alla lettera. In modalità desktop non esiste alcun confine di isolamento: il bot esegue i comandi shell con l’utente che esegue il processo API, usando la home directory, le chiavi SSH, le credenziali cloud e .env di quell’utente. Il testo di una pagina web letta dal bot diventa un comando sul server. 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 fisicamente, oppure non usarla affatto. Cambiare provider inserisce un container intorno a questo percorso verso le pagine web, invece di chiuderlo; assegnare al bot un backend di ricerca SearXNG dedicato copre la stessa superficie di injection dal lato della ricerca.

docker costituisce un confine reale tra i bot e l’host, ma un confine debole tra i bot stessi. Per impostazione predefinita, condividono un unico Team Computer; la documentazione del runtime dei computer specifica che i bot del Team condividono l’utente del sistema operativo, i profili del browser, l’accesso alla shell e a X11, e che le directory per bot organizzano il lavoro ma non costituiscono confini di sicurezza. Pertanto, qualsiasi bot del Team può leggere i file di un altro bot del Team. Un bot che richiede un isolamento dedicato deve essere eseguito su un Private Computer, che il provider docker avvia come container separato e adiacente, sulla propria rete. Il supervisore che crea questi container, tuttavia, monta /var/run/docker.sock; la documentazione self-host lo afferma chiaramente: l’accesso a quel socket equivale al controllo dell’host Docker. Mantieni quindi privato il supervisore. .env.example tratta SANDBOX_SUPERVISOR_TOKEN come una credenziale dedicata, distinta da BETTER_AUTH_SECRET, richiesta dalle sandbox Docker al di fuori dello sviluppo locale; il prodotto viene fornito con un valore segnaposto leggibile da chiunque su GitHub. Assegnale un valore casuale dedicato. Per ottenere il massimo isolamento disponibile in questo contesto, 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 dell’agente è fare in modo che la sua macchina non abbia alcun valore.

Dove vanno inserite le chiavi API dei modelli?

Rakazo non gestisce la fatturazione dei modelli. La chiave deve essere fornita dall'utente. .env.example imposta PI_DEFAULT_PROVIDER=openrouter, quindi OPENROUTER_API_KEY è la posizione abituale e le chiavi dei provider funzionano tramite la stessa impostazione.

Conserva la chiave in .env e non inserirla in alcun file di cui esegui il commit. Entrambi i comandi compose presenti nel repository passano --env-file .env, quindi i valori raggiungono i container senza essere mai scritti nei file YAML monitorati da git. Puoi anche lasciare vuoto OPENROUTER_API_KEY e collegare un modello nell'app dopo la registrazione. Questo è un ulteriore motivo per cui ENCRYPTION_KEY deve contenere un valore realmente casuale, anziché 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, e un limite per chiave è l'unico blocco che non dipende dal monitoraggio manuale. Assegna a questa chiave un nome dedicato, così potrai revocarla singolarmente. Se stai configurando il sistema per un team anziché per te stesso, un unico gateway di OneCLI davanti agli agenti di tutti risolve lo stesso problema in modo diverso, perché mantiene le chiavi dei provider in un unico punto invece di conservarne una per ogni persona.

Passare dalla modalità di sviluppo a un'installazione adatta a restare in esecuzione

Il repository include un file Compose per la produzione che avvia Postgres, l'API, il worker, l'app web e Caddy per i certificati TLS (transport layer security), che Caddy ottiene automaticamente. Caddy è l'unico servizio che pubblica porte. Per i computer dei bot usa E2B per impostazione predefinita. Un overlay opt-in, infra/compose/docker-compose.prod.docker.yml, usa invece computer Docker locali nello stesso stack. La documentazione avverte che il supervisore aggiunto da questo overlay dispone sul sistema host di privilegi equivalenti a root.

sudo DEPLOY_USER=deploy bash infra/compose/harden-host.sh
docker compose --env-file .env -f infra/compose/docker-compose.prod.yml \
  build --build-arg GIT_SHA=$(git rev-parse HEAD)
docker compose --env-file .env -f infra/compose/docker-compose.prod.yml \
  up -d --wait --pull never
curl --fail https://app.example.com/health

Create un account deploy che consenta l'accesso solo tramite chiave e verificate di potervi accedere prima di eseguire lo script. harden-host.sh disabilita l'accesso SSH tramite password e l'accesso di root, limita la frequenza delle connessioni SSH, consente tramite UFW (uncomplicated firewall) soltanto SSH, HTTP e HTTPS e abilita fail2ban, gli aggiornamenti di sicurezza automatici, AppArmor e le regole di audit. Leggetelo prima di eseguirlo, perché modifica le modalità di accesso e ricarica SSH. Lasciate aperta la console del provider finché un nuovo accesso SSH non ha esito positivo.

La configurazione .env per la produzione richiede più impostazioni di quella per lo sviluppo. La documentazione dell'installazione autonoma elenca questi requisiti minimi, oltre ai secret.

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
SIGNUPS_ENABLED=true
SIGNUP_ALLOWLIST=you@example.com
SANDBOX_PROVIDER=e2b
AGENT_RUNTIME=pi
WAKEUP_DRIVER=graphile
DATA_DIR=/data
RAKAZO_DEPLOY_DIR=/srv/rakazo
RAKAZO_IMAGE_TAG=local
POSTGRES_PASSWORD=<random, URL-safe>
BETTER_AUTH_SECRET=<random>
ENCRYPTION_KEY=<64 random hex characters>
SCREEN_PROXY_SECRET=<random>
E2B_API_KEY=<your key>
OPENROUTER_API_KEY=<your key>

Create un record A che punti al server prima del primo up. Caddy richiede un certificato per il nome indicato in RAKAZO_HOST. La richiesta fallisce se il nome non risolve verso questo server o se la porta 80 non è raggiungibile dall'esterno.

Impostate SIGNUP_ALLOWLIST sul vostro indirizzo fin dall'inizio. SIGNUPS_ENABLED=true è il valore predefinito e viene applicato soltanto al primo avvio dell'API. Di conseguenza, un'istanza esposta su un nome pubblico accetta registrazioni da chiunque la trovi. Un'allowlist non vuota viene applicata a ogni avvio e sostituisce l'elenco salvato. Se SMTP non è configurato, il primo account incluso nell'allowlist può registrarsi senza verificare il proprio indirizzo email. Create quindi il vostro account prima di rendere pubblico il nome. Configurate prima l'allowlist. Potrete renderla meno restrittiva in seguito, se necessario. Se sullo stesso server eseguite già diversi servizi e preferite mantenere un unico elenco di utenti invece di un'allowlist per ogni applicazione, collocare un'istanza di Authentik davanti ai servizi trasferisce questa decisione al proxy. Authentik si colloca però davanti agli account Better Auth propri di Rakazo, invece di sostituirli.

Considerate docs/self-host.md nel repository come la fonte autorevole per le impostazioni di produzione, perché cambia insieme al codice mentre questa guida non viene aggiornata automaticamente. Poiché il lavoro viene eseguito da Compose, si applicano le regole consuete. Le nozioni di base su Docker Compose per un VPS spiegano perché --env-file e i volumi denominati diventano 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/. restore.sh funziona nello stack Compose di sviluppo, su un database vuoto e con i servizi dell’applicazione arrestati; non legge i file di backup di produzione. Per una macchina da cui dipendi, installa infra/compose/backup-prod.sh come /usr/local/sbin/rakazo-backup insieme al timer fornito dal repository. Scrive un dump verificato e un archivio dei dati dell’applicazione in /var/backups/rakazo e, per impostazione predefinita, conserva i tre snapshot verificati più recenti, configurati tramite RAKAZO_BACKUP_KEEP. Rimuove quelli meno recenti solo dopo la verifica di un nuovo snapshot, quindi la rotazione avviene automaticamente. Un backup che si trova sullo stesso disco del database non è un backup: copialo fuori dal server. Quindi ripristinalo 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, essere in esecuzione ma non ancora pronto, oppure essere stato avviato senza l'overlay docker-compose.postgres-host.yml, che pubblica la porta 5433 sull'host. 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 controllo di salute 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 elimina, insieme ai dati in esso contenuti.

La porta è già occupata. L'avvio di Postgres non riesce con bind: address already in use quando un altro processo usa già la porta 5433, nella maggior parte dei casi un precedente stack Rakazo che non è stato arrestato. sudo ss -lntp | grep 5433 identifica il processo. L'overlay legge la porta dell'host da POSTGRES_HOST_PORT, quindi puoi modificarla, purché modifichi anche DATABASE_URL.

Un bot non riceve mai un computer. Se sono presenti SANDBOX_PROVIDER=docker e nessuna immagine rakazo/computer:local, non c'è nulla da avviare. docker image ls rakazo/computer lo conferma con una sola riga e pnpm sandbox:build risolve il problema. Se il supervisore non riesce ad accedere al socket Docker, non può creare neppure i container, e 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 sia andata in crash.

pnpm install si comporta in modo anomalo. Controlla node -v prima di qualsiasi altra cosa. Il workspace dichiara ^22.22.2 || ^24.0.0 || >=26.0.0, quindi 23.x, 25.x e qualsiasi versione 22.x precedente a 22.22.2 non sono supportate; una versione di Node non supportata causa errori nel codice delle dipendenze invece di mostrare un messaggio relativo alle versioni.

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

Aggiornamento di un checkout bloccato

Il percorso di aggiornamento descritto nella documentazione self-host per uno stack Compose di produzione compilato dal proprio checkout è breve: scaricare il nuovo codice sorgente, quindi ricompilare e riavviare l'API, il worker e l'applicazione web. Le migrazioni vengono eseguite all'avvio dell'API, perché il comando di avvio le applica prima di iniziare a servire le richieste.

sudo /usr/local/sbin/rakazo-backup
git fetch --all --tags
git checkout NEW_COMMIT_SHA
export GIT_SHA=$(git rev-parse HEAD)
docker compose --env-file .env -f infra/compose/docker-compose.prod.yml \
  up -d --wait --pull never --build api worker web

Eseguire prima un backup. Le migrazioni avanzano e una beta non offre un percorso di rollback affidabile. Se il checkout è precedente al 30 August 2026, incluso il commit v0.1.0-beta, leggere la nota della documentazione sulla migrazione 20260830200000_space_scope_names_and_user_credentials prima di eseguire l'aggiornamento. Si tratta di un passaggio coordinato: arrestare prima la vecchia API e il vecchio worker, quindi eseguire il controllo del confine di privacy di Space indicato nella documentazione. Leggere i commit compresi tra lo SHA bloccato e quello nuovo prima di applicarli, perché un progetto così giovane può rinominare le variabili d'ambiente senza comunicarlo; una variabile mancante si manifesta come un servizio che si avvia e poi termina. Se si sta ancora valutando se Rakazo sia la soluzione adatta da eseguire, la panoramica degli agenti AI self-hosted illustra quali altre soluzioni rientrano in questa categoria e quanto costa 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. Con SANDBOX_PROVIDER=docker, il computer dei bot aggiunge un container con un desktop grafico, un display X separato e un processo Chrome per ogni bot attivo, il tutto entro un limite predefinito di 2 GB di memoria e due CPU. La documentazione per l'installazione self-hosted disponibile in v0.3.1 non indica una dimensione per l'host. La versione beta di agosto 2026 indicava 2 vCPU e 4 GB come sufficienti per la sola API, il worker e Postgres, quando E2B ospitava i desktop dei bot. Considera 4 GB il minimo per il control plane e usa una dimensione maggiore quando i desktop vengono eseguiti sulla tua macchina.

La sandbox desktop è sicura su un server?

No. La documentazione per l'installazione self-hosted specifica che desktop esegue i comandi direttamente sull'host dell'API e del worker. Il bot opera quindi con l'account che esegue il processo e può accedere ai file e alle credenziali di quell'account. Non usarla su un server pubblico o condiviso. Usa docker, assegnando a un bot un Computer privato quando non deve condividere file con gli altri bot del workspace, oppure e2b quando accedono più persone.

Quale versione di Rakazo devo installare?

Al 21 ottobre 2026, la versione più recente è v0.3.1, pubblicata il 19 ottobre 2026 e contrassegnata come Latest. Effettua il checkout del commit indicato, 926710a09b30a6c1f83029da88dfe06656b031f2, invece di seguire main o la prerelease di agosto v0.1.0-beta. Un branch può cambiare nel tempo e un tag può essere riassegnato. Nessuno dei due identifica quindi un albero del codice a cui puoi tornare con certezza. Registra il commit, perché il rollback è possibile solo se sai quale versione funzionava.

Dove devo inserire la mia chiave API OpenRouter?

In .env come OPENROUTER_API_KEY, mai in un file compose di cui esegui il commit. Entrambi i comandi compose presenti nel repository passano --env-file .env. Il valore raggiunge quindi i container senza essere scritto nei file YAML sotto versionamento. Puoi anche lasciarlo vuoto e collegare un modello nell'app dopo la registrazione. Imposta un limite di spesa sulla chiave presso il provider, perché un bot in loop continua a chiamare il modello finché qualcosa non lo interrompe.

Mi servono un nome di dominio e TLS?

Per qualsiasi utilizzo oltre il primo test, sì. 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 utilizzare 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.