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 lancer des pairs ou des sous-agents à courte durée de vie.

C’est la raison pour laquelle cette architecture doit fonctionner 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 joignable pendant votre sommeil. La mise en veille d’un ordinateur portable interrompt la queue.

Rakazo est encore en bêta précoce en août 2026. Considérez donc cette installation comme une configuration fonctionnelle, et non comme une appliance finalisée. La stack est entièrement 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 queue dans Postgres. Il n’y a 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 est l’autre possibilité.

Pourquoi un plan 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 des sandboxes en est un quatrième. Ensuite, chaque bot en cours d’exécution obtient un conteneur qui contient un bureau Linux graphique et un navigateur.

La documentation d’auto-hébergement du projet fournit 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. Avec SANDBOX_PROVIDER=docker, 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 de la sandbox qui augmente 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 aux agents, cet article explique en détail la quantité réelle de RAM et de CPU nécessaire à un VPS d’agent.

Un réglage permet d’éviter que la situation ne s’aggrave. .env.example fournit SANDBOX_IDLE_MS=600000 avec le commentaire indiquant qu’il met en pause les machines E2B ou arrête les conteneurs 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 ouvert conserverait de la mémoire indéfiniment.

L’espace disque compte également. L’image de la sandbox, les modules Node et le volume Postgres partagent le même disque. 40 GB constitue donc un bon point de départ.

Épinglez 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 le commit pointé par v0.1.0-beta. É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 vers un autre commit. Aucun des deux n’identifie donc un arbre auquel vous pouvez revenir. L’identifiant d’un commit ne change pas. Notez le vôtre avec les autres informations de votre serveur. En cas de problème après une mise à niveau, la solution rapide et économique consiste à git checkout <old commit> puis à reconstruire. Cela ne fonctionne que si vous savez quel commit fonctionnait.

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 de l’archive 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. Vérifiez d’abord ce que cela autorise : l’appartenance au groupe docker équivaut à disposer des privilèges root sur la machine, car tout membre de 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 refuse ces valeurs de remplacement hors du développement. Un déploiement partiellement configuré échoue donc clairement au lieu d’utiliser 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, puis 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. Le premier build télécharge donc beaucoup de données et prend du temps. Vérifiez qu’elle a bien été créée avec docker image ls rakazo/computer. La commande doit afficher une ligne.

Le fichier Compose publie Postgres sur 127.0.0.1:5433:5432, limité à loopback. Laissez cette configuration telle quelle. 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 lit plutôt POSTGRES_PASSWORD. Définissez-y une chaîne aléatoire lorsque vous passerez à la production.

La première exécution

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ù vous devriez obtenir une page de connexion.

Sur un VPS, vous n’êtes pas connecté directement à 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

Soyez attentif à 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 actif.

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 obtient 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 les ordinateurs des bots restent séparés 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 claire : ne l’utilisez pas sur un serveur public ou partagé.
• fake est un émulateur in-process destiné aux tests. Ce n’est pas un environnement d’exécution.

Prenez littéralement l’avertissement concernant le mode desktop. Dans ce mode, il n’existe aucune frontière d’isolation. Le bot exécute donc les commandes shell avec les privilèges de l’utilisateur qui exécute le processus de l’API, ainsi qu’avec son répertoire personnel, ses clés SSH, ses identifiants cloud et son .env. Le texte d’une page web que le bot lit devient une commande exécutée sur votre serveur. Utiliser le mode desktop sur un serveur permet à un bot d’accéder à vos identifiants. Utilisez-le sur une machine devant laquelle vous êtes assis, ou ne l’utilisez pas du tout.

docker constitue une véritable frontière, mais elle n’est pas parfaite. Un bot ne peut pas lire les fichiers d’un autre bot, car chacun possè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 équivaut au contrôle de 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 placeholder 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 attribuez à 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 mauvaise action 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 ; OPENROUTER_API_KEY est donc l’emplacement habituel, et les clés des fournisseurs utilisent 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 sont donc accessibles 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’assistant de configuration. C’est une raison supplémentaire pour laquelle ENCRYPTION_KEY doit avoir une vraie valeur aléatoire, et non la valeur factice fournie.

Définissez une limite de dépenses sur la clé auprès du fournisseur avant qu’un bot ne l’utilise. Un bot qui boucle dépense de l’argent, 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 distinct afin de pouvoir la révoquer seule.

Passer du mode dev à 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 la connexion 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 la façon dont vous vous connectez. 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.

Configurez également SIGNUP_ALLOWLIST=you@example.com. SIGNUPS_ENABLED=true est la valeur par défaut. Une instance accessible avec 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 assouplir ce réglage plus tard si nécessaire.

Considérez docs/self-host.md dans le dépôt comme la référence pour les paramètres de production, car il é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 reste inactive pendant plusieurs mois.

Sauvegardes

Postgres et le répertoire data/ constituent l’ensemble de l’instance.

./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. Effectuez ensuite une restauration 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. Soit le conteneur Postgres n’est pas démarré, soit il est démarré mais pas encore prêt. Exécutez docker compose --env-file .env -f infra/compose/docker-compose.yml ps et recherchez un service postgres 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 répond à cette question en une ligne, et pnpm sandbox:build corrige le problème. Si le supervisor ne peut pas accéder à la socket Docker, il ne peut pas non plus créer de conteneurs, et 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, donc une commande unique exécutée dans l’ordinateur d’un bot est interrompue après cinq minutes. Augmentez cette valeur pour les builds lents au lieu de supposer que le sandbox a planté.

pnpm install échoue de manière déroutante. Vérifiez node -v avant toute autre chose. Le workspace déclare >=22, et une version ancienne 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, schéma compris. Une valeur http://127.0.0.1:5173 obsolète dans l’un d’eux est généralement la cause d’une session qui ne reste jamais ouverte.

Mise à jour d’un checkout épinglé

La procédure de mise à niveau de 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 jeune peut renommer 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 réellement adapté à votre usage, le récapitulatif des agents IA auto-hébergés présente les autres solutions de cette catégorie et le coût du maintien de chacune en fonctionnement.

FAQ

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

Non. Postgres, l’API, le worker, le sandbox supervisor et l’application web s’exécutent en même temps. Avec SANDBOX_PROVIDER=docker, chaque bot actif ajoute un conteneur qui contient 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 desktop sandbox 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 du compte qui exécute le processus. Les fichiers et les identifiants de ce compte sont donc accessibles. Le dépôt indique de ne pas 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 août 2026, il existe un seul tag : v0.1.0-beta, publié le 13 août 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, et un tag peut être déplacé. Aucun des deux ne désigne donc un arbre de sources 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 le nom 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 ainsi 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é chez le 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 ?

Oui, dès que vous allez au-delà d’un premier test. 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 test, vous pouvez ignorer le domaine : exécutez pnpm dev et transférez le port 5173 via SSH au lieu de le publier.