Installer Rakazo sur un VPS avec Docker Compose

Ce que l’auto-hébergement de Rakazo exécute réellement

L’auto-hébergement de Rakazo consiste à exécuter cinq éléments sur un même serveur Linux : PostgreSQL, un processus Graphile Worker, l’API, l’application web et un conteneur sandbox pour chaque bot actif. Rakazo est une alternative open source à Grok Bot, publiée par elie222 sous licence Apache 2.0. Chaque bot dispose de son propre thread, de son propre ordinateur, de sa propre mémoire et de son propre historique. Il peut aussi créer des pairs ou des sous-agents à durée de vie courte. Si les termes mémoire, sous-agent et appel d’outil ne vous sont pas familiers dans ce contexte, un parcours progressif du fonctionnement réel des agents mérite d’être consulté avant d’aller plus loin. La plupart des paramètres ci-dessous ne prennent leur sens qu’une fois que vous pouvez visualiser ce que fait un bot lorsqu’il se réveille.

C’est précisément pour cette raison que Rakazo doit être exécuté sur un VPS (virtual private server), et non sur un ordinateur de bureau. Un bot qui conserve une mémoire et exécute des tâches planifiées doit rester accessible pendant votre sommeil. Un ordinateur portable qui se met en veille interrompt la file d’attente.

En août 2026, Rakazo est encore en bêta précoce. Considérez donc cette configuration comme un environnement fonctionnel, et non comme une appliance finalisée. La stack est entièrement écrite en TypeScript : React 19 et Vite pour l’application web, Hono pour l’API, Postgres avec Prisma, Better Auth pour les comptes et Graphile Worker pour les tâches en arrière-plan. Graphile Worker stocke sa file d’attente dans Postgres. Vous n’avez donc ni Redis ni second datastore à exécuter. .env.example définit WAKEUP_DRIVER=graphile, ce qui signifie que le réveil d’un bot correspond à une tâche gérée par Postgres. Si vous arrêtez Postgres, toutes les actions planifiées des bots s’arrêtent également. Si vous préférez assembler un agent à partir de composants plutôt que d’exécuter le produit de quelqu’un d’autre, construire votre propre agent à partir de composants constitue l’autre possibilité.

Pourquoi une offre de 1 GB ne suffira pas

Comptez les processus. Postgres en est un. L’API est un processus Node. Le worker en est un deuxième. L’application web en est un troisième. Le superviseur du sandbox en est un quatrième. Ensuite, chaque bot en cours d’exécution reçoit un conteneur avec un bureau Linux graphique et un navigateur.

La documentation d’auto-hébergement du projet donne un chiffre réaliste : une machine avec 2 vCPU et 4 GB suffit pour l’API, le worker et Postgres lorsque E2B héberge les bureaux des bots. Ce chiffre concerne uniquement le control plane, la partie lourde étant hébergée ailleurs. Définissez SANDBOX_PROVIDER=docker et ces bureaux sont déplacés sur votre VPS. Les 4 GB deviennent donc un minimum, et non un objectif. Commencez avec 8 GB si vous prévoyez de laisser plusieurs bots actifs, puis mesurez la consommation réelle avec docker stats pendant qu’un bot travaille. C’est le navigateur à l’intérieur du sandbox qui fait varier la consommation mémoire. Une fiche technique ne vous donnera donc pas la réponse. Pour connaître la méthode générale de dimensionnement d’une machine destinée au travail d’agents, la quantité réelle de RAM et de CPU nécessaire à un VPS d’agent détaille la mesure.

Un réglage évite que la situation s’aggrave. .env.example fournit SANDBOX_IDLE_MS=600000 avec un commentaire indiquant qu’il met en pause les machines E2B, ou arrête celles gérées par Docker, après ce nombre de millisecondes d’inactivité. Après dix minutes d’inactivité, la machine est supprimée. La valeur minimale acceptée est 30000. Sans ce réglage, chaque bot que vous avez ouvert conserverait de la mémoire indéfiniment.

L’espace disque compte également. L’image du sandbox, les modules Node et le volume Postgres utilisent le même disque. Une capacité de 40 GB constitue donc un point de départ raisonnable.

Verrouillez une version avant le clonage

Rakazo évolue rapidement et main n’est pas une release. Au 16 août 2026, le dépôt contient exactement un tag, v0.1.0-beta, publié le 13 août 2026 et marqué comme prerelease.

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

C’est ce commit que v0.1.0-beta désigne. Épinglez le commit plutôt que la branche ou le tag. Une branche évolue au prochain git pull, et un tag est un libellé modifiable qu’un mainteneur peut faire pointer ailleurs. Aucun des deux n’identifie donc un arbre vers lequel vous pourrez revenir. L’identifiant d’un commit ne peut pas changer. Notez-le avec les autres informations de votre serveur, car lorsqu’une mise à niveau casse le service, la solution rapide consiste à git checkout <old commit> et à reconstruire. Cela ne fonctionne que si vous savez quel commit fonctionnait. Cette précision est une contrainte liée à la phase bêta, pas une règle universelle. Un projet qui publie des versions planifiées peut être épinglé sur un tag publié, comme une stack auto-hébergée plus légère comme openGym.

Prérequis : Node 22, pnpm 9 et Docker

node -v
pnpm -v
docker --version

package.json déclare "engines": { "node": ">=22" } et "packageManager": "pnpm@9.15.0". node -v doit donc afficher v22 ou une valeur supérieure. Le paquet Node des dépôts Ubuntu est généralement plus ancien. Installez Node depuis NodeSource ou nvm. pnpm est fourni avec Node via corepack :

corepack enable
corepack prepare pnpm@9.15.0 --activate

Docker Engine et le plugin compose couvrent le reste. Votre utilisateur doit pouvoir accéder au daemon. Si docker ps renvoie permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock, ajoutez votre utilisateur au groupe docker, puis ouvrez un nouveau shell de connexion. Comprenez d’abord les droits accordés : l’appartenance au groupe docker équivaut à root sur la machine, car toute personne appartenant à ce groupe peut démarrer un conteneur qui monte le système de fichiers de l’hôte.

Configurer .env, puis démarrer Postgres

cp .env.example .env
chmod 600 .env

Deux valeurs doivent être modifiées avant toute exposition sur le réseau. .env.example fournit BETTER_AUTH_SECRET=replace-with-32-plus-character-secret et ENCRYPTION_KEY=replace-with-64-char-hex-or-passphrase. Rakazo rejette ces valeurs d’exemple hors du développement. Un déploiement partiellement configuré échoue donc explicitement au lieu de fonctionner avec un secret publié dans le dépôt.

openssl rand -base64 48
openssl rand -hex 32

Démarrez ensuite la base de données seule et exécutez les migrations.

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 construit l’image de l’ordinateur du bot, définie dans package.json comme docker build -t rakazo/computer:local infra/sandboxes/computer. Il s’agit d’une image graphique. La première compilation télécharge donc de nombreux éléments et prend du temps. Vérifiez qu’elle a bien été créée avec docker image ls rakazo/computer. Cette commande doit afficher une ligne.

Le fichier Compose publie Postgres sur 127.0.0.1:5433:5432, qui est limité à la loopback. Conservez cette configuration. Les identifiants de développement sont rakazo:rakazo et se trouvent dans le dépôt. Un port Postgres accessible depuis Internet avec un mot de passe publié est détecté par les scanners en quelques heures. Le fichier Compose de production utilise plutôt POSTGRES_PASSWORD. Définissez-y une chaîne aléatoire lorsque vous passerez à la production.

Premier démarrage

pnpm dev

Cette commande démarre quatre éléments : l’API sur le port 3100, Graphile Worker, l’application web Vite sur le port 5173 et le superviseur de sandbox sur le port 7091. L’application est accessible à l’adresse http://127.0.0.1:5173, où une page de connexion doit s’afficher.

Sur un VPS, vous n’êtes pas devant cette machine. Vous ne devez donc pas publier le port 5173 pour y accéder. Transférez plutôt les ports via SSH (secure shell) depuis votre propre machine.

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

Faites attention à la différence entre les deux modes d’exécution. pnpm dev exécute Vite sur l’hôte, avec une écoute locale. Le service web du fichier Compose publie 5173:5173 sur toutes les interfaces. Si vous démarrez toute la stack Compose de développement sur un VPS public, l’application est exposée. Utilisez donc le fichier de production et son reverse proxy pour tout service que vous laissez fonctionner.

Quel fournisseur de sandbox est sûr sur un serveur ?

C’est le seul paramètre qu’il faut absolument configurer correctement. SANDBOX_PROVIDER dans .env accepte quatre valeurs.

• docker est la valeur par défaut. Chaque bot reçoit son propre conteneur sur votre machine, créé à partir de l’image produite par pnpm sandbox:build. C’est la configuration auto-hébergée la plus rapide.
• e2b exécute les ordinateurs des bots sur E2B et nécessite E2B_API_KEY. Le projet le recommande pour les déploiements publics ou multi-utilisateurs, car cette solution sépare les ordinateurs des bots de l’hôte qui exécute votre API et votre base de données.
• desktop exécute directement les commandes du bot sur l’hôte de l’API et des workers. La documentation du dépôt est catégorique : ne l’utilisez pas sur un serveur public ou partagé.
• fake est un émulateur intégré au processus destiné aux tests. Ce n’est pas un environnement d’exécution.

Prenez cet avertissement concernant le mode desktop au pied de la lettre. En mode desktop, il n’existe aucune limite d’isolation. Le bot exécute donc les commandes shell avec le compte qui exécute le processus de l’API, son répertoire personnel, ses clés SSH, ses identifiants cloud et son .env. Le texte d’une page web lue par le bot devient une commande sur votre serveur. Utiliser le mode desktop sur un serveur permet à un bot de récupérer vos identifiants. Utilisez-le sur une machine devant laquelle vous êtes assis, ou pas du tout. Changer de fournisseur place un conteneur autour de ce parcours vers les pages web, mais ne le supprime pas. Donner à un bot son propre backend de recherche SearXNG couvre la même surface d’injection du côté de la recherche.

docker constitue une véritable limite, mais elle n’est pas parfaite. Un bot ne peut pas lire les fichiers d’un autre bot, car chacun dispose de son propre conteneur. En revanche, le superviseur qui crée ces conteneurs monte /var/run/docker.sock, et le contrôle du socket Docker de l’hôte permet de contrôler l’hôte. Gardez donc le superviseur privé. .env.example documente SANDBOX_SUPERVISOR_TOKEN comme un identifiant facultatif pour un service séparé. Lorsqu’il est vide, sa valeur par défaut est BETTER_AUTH_SECRET. Laisser ce secret à sa valeur d’exemple protège donc le service qui crée les conteneurs avec une chaîne que n’importe qui peut lire sur GitHub. Définissez les deux valeurs. Pour obtenir la séparation la plus forte disponible ici, utilisez e2b, ou donnez à Rakazo une machine qui ne contient rien d’autre. C’est le même raisonnement que pour exécuter des agents de programmation dans une VM jetable : le moyen le moins coûteux de survivre à une erreur d’un agent consiste à faire en sorte que sa machine ne vaille rien.

Où placer les clés d’API des modèles ?

Rakazo ne gère pas la facturation des modèles. Vous devez fournir la clé. .env.example définit PI_DEFAULT_PROVIDER=openrouter, donc OPENROUTER_API_KEY est l’emplacement habituel, et les clés des fournisseurs fonctionnent avec le même paramètre.

Conservez la clé dans .env et ne l’incluez dans aucun fichier que vous validez dans git. Les deux commandes compose du dépôt transmettent --env-file .env. Les valeurs parviennent ainsi aux conteneurs sans jamais être écrites dans un fichier YAML suivi par git. Vous pouvez aussi laisser OPENROUTER_API_KEY vide et coller une clé dans l’application pendant l’onboarding. C’est une raison supplémentaire pour laquelle ENCRYPTION_KEY doit contenir une vraie valeur aléatoire plutôt que le placeholder fourni.

Définissez une limite de dépenses pour la clé chez le fournisseur avant qu’un bot ne l’utilise. Un bot qui boucle est un bot qui dépense, et une limite par clé est le seul mécanisme d’arrêt qui ne dépend pas de votre surveillance. Donnez à cette clé un nom qui lui est propre afin de pouvoir la révoquer seule. Si vous configurez cela pour une équipe plutôt que pour vous-même, la passerelle unique de OneCLI devant les agents de toute l’équipe est une autre réponse au même problème : les clés des fournisseurs sont conservées au même endroit, au lieu d’être dupliquées pour chaque personne.

Passer du mode développement à une configuration que vous pouvez laisser fonctionner

Le dépôt fournit un fichier Compose de production qui exécute Postgres, l’API, le worker, l’application web et Caddy pour les certificats TLS (transport layer security), qu’il obtient automatiquement. Il attend E2B pour les ordinateurs des bots.

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 désactive l’authentification SSH par mot de passe, configure les règles UFW (uncomplicated firewall) pour SSH, HTTP et HTTPS, active fail2ban et applique les profils AppArmor. Lisez-le avant de l’exécuter, car il modifie votre méthode de connexion. Gardez une deuxième session SSH ouverte pendant son exécution.

Le .env de production nécessite davantage de configuration que celui de développement. La documentation d’auto-hébergement indique ce minimum.

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

Pointez un enregistrement A vers le serveur avant ce premier up. Caddy demande un certificat pour le nom indiqué dans RAKAZO_HOST. La demande échoue si ce nom ne résout pas vers ce serveur ou si le port 80 est fermé depuis l’extérieur.

Définissez également SIGNUP_ALLOWLIST=you@example.com. SIGNUPS_ENABLED=true est la valeur par défaut. Une instance accessible depuis un nom public accepte donc les inscriptions de toute personne qui la trouve, et chaque nouveau compte obtient un ordinateur. Commencez par utiliser une allowlist. Vous pourrez l’assouplir plus tard si nécessaire. Si vous exécutez déjà plusieurs services sur le même serveur et préférez gérer une seule liste d’utilisateurs plutôt qu’une allowlist par application, placer une instance Authentik devant ces services déplace cette décision vers le proxy. Cette configuration reste toutefois devant les comptes Better Auth propres à Rakazo, qu’elle ne remplace pas.

Considérez docs/self-host.md dans le dépôt comme la référence pour les paramètres de production, car ce fichier évolue avec le code, contrairement à ce guide. Puisque Compose se charge de l’exécution, les règles habituelles s’appliquent. Les bases de Docker Compose pour un VPS expliquent pourquoi --env-file et les volumes nommés deviennent encore plus importants lorsqu’une stack doit rester sans intervention pendant plusieurs mois.

Sauvegardes

Postgres et le répertoire data/ constituent l’instance complète.

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

backup.sh effectue un dump de Postgres et archive data/. Pour une machine dont vous dépendez, installez infra/compose/backup-prod.sh en tant que /usr/local/sbin/rakazo-backup avec le timer fourni par le dépôt, afin que la rotation s’effectue automatiquement. Une sauvegarde stockée sur le même disque que la base de données n’est pas une sauvegarde : copiez-la hors de la machine. Restaurez-la ensuite une fois sur un serveur de secours, avant d’en avoir besoin.

Pourquoi cela échoue et ce que vous verrez

pnpm db:migrate ne peut pas joindre la base de données. La migration indique qu’elle ne peut pas joindre le serveur de base de données à l’adresse 127.0.0.1:5433. Le conteneur Postgres n’est peut-être pas démarré, ou il est démarré mais pas encore prêt. Exécutez docker compose --env-file .env -f infra/compose/docker-compose.yml ps et vérifiez que le service postgres est indiqué comme healthy, car le fichier Compose lui attribue un health check exécuté toutes les trois secondes. Un conteneur qui redémarre en boucle indique généralement que le volume pgdata a été créé avec d’autres identifiants. docker compose ... down -v le supprime, ainsi que les données qu’il contient.

Le port est déjà utilisé. Le démarrage de Postgres échoue avec bind: address already in use lorsqu’un autre processus utilise 5433, le plus souvent une ancienne stack Rakazo que vous avez oublié d’arrêter. sudo ss -lntp | grep 5433 indique le processus concerné.

Un bot n’obtient jamais d’ordinateur. Avec SANDBOX_PROVIDER=docker et sans image rakazo/computer:local, rien ne peut être démarré. docker image ls rakazo/computer le signale en une ligne, et pnpm sandbox:build corrige le problème. Si le supervisor ne peut pas accéder au socket Docker, il ne peut pas non plus créer de conteneurs. Le message indique le chemin : permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock.

Une commande longue s’arrête en cours d’exécution. .env.example définit SANDBOX_COMMAND_TIMEOUT_MS=300000. Une seule commande exécutée dans l’ordinateur d’un bot est donc interrompue après cinq minutes. Augmentez cette valeur pour les builds lents au lieu de conclure que le sandbox a planté.

pnpm install échoue de manière difficile à diagnostiquer. Vérifiez node -v avant toute autre chose. Le workspace déclare >=22, et une ancienne version de Node échoue dans le code des dépendances au lieu d’afficher un message concernant les versions.

La connexion fonctionne en local, mais pas via le domaine. BETTER_AUTH_URL, WEB_ORIGIN et API_URL doivent tous contenir la même origine publique que la barre d’adresse, y compris le scheme. Une valeur http://127.0.0.1:5173 obsolète dans l’un d’eux est généralement à l’origine d’une session qui n’est jamais conservée.

Mise à jour d’un checkout épinglé

La procédure de mise à niveau indiquée dans la documentation d’auto-hébergement est courte : récupérez les nouvelles sources, exécutez la migration de la base de données, puis redémarrez l’API et le 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

Commencez par effectuer une sauvegarde. Les migrations avancent, et une version bêta ne vous offre aucune procédure de retour fiable. Lisez les commits compris entre votre SHA épinglé et le nouveau avant de les appliquer, car un projet aussi récent renomme parfois des variables d’environnement sans l’annoncer. Une variable manquante se manifeste par un service qui démarre, puis s’arrête. Si vous déterminez encore si Rakazo est le bon logiciel à exécuter, le comparatif des agents IA auto-hébergés présente les autres solutions de cette catégorie et le coût de leur maintien en fonctionnement.

FAQ

Puis-je exécuter Rakazo sur un VPS de 1 GB ?

Non. Postgres, l’API, le worker, le superviseur des sandbox et l’application web s’exécutent simultanément. Avec SANDBOX_PROVIDER=docker, chaque bot actif ajoute un conteneur contenant un bureau graphique et un navigateur. La documentation du projet indique que 2 vCPU et 4 GB suffisent pour l’API, le worker et Postgres uniquement lorsque E2B héberge les bureaux des bots. Considérez 4 GB comme le minimum pour le control plane. Prévoyez davantage lorsque les bureaux s’exécutent sur votre machine.

Le fournisseur de sandbox de bureau est-il sûr sur un serveur ?

Non. desktop exécute directement les commandes du bot sur l’hôte de l’API et du worker, avec les droits de l’utilisateur qui exécute ce processus. Les fichiers et les identifiants de cet utilisateur sont donc accessibles. Le dépôt déconseille de l’utiliser sur un serveur public ou partagé. Utilisez docker pour un conteneur par bot, ou e2b lorsque plusieurs personnes se connectent.

Quelle version de Rakazo dois-je installer ?

Au 16 August 2026, il existe un seul tag : v0.1.0-beta, publié le 13 August 2026 et marqué comme prerelease. Récupérez le commit vers lequel il pointe, 53b119a68d9ef843d23aa3b7e3719b6be7b51fdb, plutôt que de suivre main. Une branche peut évoluer sans que vous le remarquiez et un tag peut être réassigné. Aucun des deux n’identifie donc un arbre source auquel vous pouvez revenir. Notez le commit, car un rollback n’est possible que si vous savez lequel fonctionnait.

Où dois-je placer ma clé API OpenRouter ?

Dans .env, sous la forme OPENROUTER_API_KEY, et jamais dans un fichier compose que vous commitez. Les deux commandes compose du dépôt transmettent --env-file .env. La valeur atteint donc les conteneurs sans être écrite dans un fichier YAML suivi par le contrôle de version. Vous pouvez aussi laisser ce champ vide et coller la clé dans l’application pendant l’onboarding. Définissez une limite de dépenses pour cette clé auprès du fournisseur, car un bot bloqué dans une boucle continue d’appeler le modèle jusqu’à ce qu’un mécanisme l’arrête.

Ai-je besoin d’un nom de domaine et de TLS ?

Pour tout usage dépassant un premier test, oui. Le fichier compose de production exécute Caddy et obtient automatiquement les certificats. RAKAZO_HOST, BETTER_AUTH_URL, WEB_ORIGIN et API_URL doivent tous utiliser la même origine HTTPS publique. Pour un premier essai, vous pouvez vous passer de domaine : exécutez pnpm dev et transférez le port 5173 via SSH au lieu de le publier.