Auto-héberger Rakazo sur un VPS : guide pratique
Installez Rakazo sur votre VPS avec Node 22, pnpm, PostgreSQL et Graphile Worker dans Docker Compose. Choisissez le sandbox provider, gérez les clés et dimensionnez cinq composants.
Ce que l’auto-hébergement de Rakazo exécute réellement
L’auto-hébergement de Rakazo consiste à exécuter cinq composants sur un même serveur Linux : PostgreSQL, un processus Graphile Worker, l’API, l’application web et un conteneur sandbox qui sert d’ordinateur aux bots. Rakazo est une alternative open source à Grok Bot, publiée par elie222 sous licence Apache 2.0. Chaque bot possède ses propres conversations, sa mémoire, ses routines et son historique. Il partage un Team Computer avec les autres bots de l’espace de travail, sauf si un Private Computer lui est attribué. Il peut aussi créer des pairs ou des sous-agents à durée de vie courte. Si des termes comme mémoire, sous-agent et appel d’outil ne vous sont pas familiers dans cette phrase, un parcours progressif du fonctionnement réel des agents mérite d’abord un après-midi, car la plupart des paramètres ci-dessous ne prennent 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 installé 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 être accessible pendant votre sommeil. Un ordinateur portable qui se met en veille interrompt la file d’attente.
Rakazo se décrit encore comme une version bêta en octobre 2026, même s’il publie désormais des releases avec un numéro stable. 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 file d’attente 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 à un job géré 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 voie.
Pourquoi une offre de 1 GB ne suffira pas
Comptez les processus. Postgres en utilise 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. Vient ensuite l’ordinateur des bots : par défaut, un conteneur Team Computer partagé qui héberge un bureau Linux graphique, avec un affichage X et un processus Chrome distincts pour chaque bot actif.
La documentation d’auto-hébergement du projet n’indique plus de taille d’hôte. La documentation à v0.3.5, consultée le 27 octobre 2026, liste uniquement les exigences logicielles. Elle indique toutefois une limite par ordinateur : avec les Docker sandboxes, RAKAZO_COMPUTER_MEMORY vaut par défaut 2g et RAKAZO_COMPUTER_CPUS vaut 2. Cette limite s’applique à chaque ordinateur, pas à chaque bot. Chaque workspace reçoit par défaut un Team Computer, et chaque Team bot actif exécute son bureau et son navigateur à l’intérieur de celui-ci. Ils partagent donc tous ces 2 GB et ces deux cœurs. Seul un bot déplacé vers un Private Computer obtient son propre conteneur et sa propre limite. Définissez SANDBOX_PROVIDER=docker pour déplacer ces bureaux sur votre VPS, en plus du control plane. Dans ce cas, 4 GB constitue un minimum, pas un objectif. Commencez avec 8 GB si vous prévoyez de laisser plusieurs bots actifs, augmentez RAKAZO_COMPUTER_MEMORY pour que l’ordinateur partagé puisse réellement utiliser cette mémoire, puis mesurez la valeur réelle avec docker stats pendant que les bots travaillent. C’est le navigateur à l’intérieur du sandbox qui détermine la consommation mémoire. Une fiche technique ne vous donnera donc pas cette information. Pour empêcher une petite machine de lancer trop de navigateurs simultanément, définissez une valeur positive pour SANDBOX_TEAM_SCREEN_LIMIT. Cette valeur limite le nombre de bureaux actifs sur un Docker Team Computer. La valeur 0 fournie par défaut ne fixe aucune limite. Si la mémoire disponible est globalement insuffisante, RAKAZO_COMPUTER_MEMORY accepte également une valeur plus faible, telle que 1536m. Pour connaître la méthode générale de dimensionnement d’une machine destinée au travail des agents, consultez la quantité réelle de RAM et de CPU nécessaire à un agent VPS, qui détaille les mesures à effectuer.
Un paramètre permet d’éviter que la situation ne s’aggrave. .env.example fournit SANDBOX_IDLE_MS=600000, et son commentaire indique que les ordinateurs sont mis en pause ou arrêtés après ce nombre de millisecondes d’inactivité. Après dix minutes d’inactivité, l’ordinateur est mis en pause ou arrêté. La valeur minimale acceptée est 30000, et 0 désactive la mise en veille après inactivité. Le même commentaire recommande 0 pour les auto-hébergements Docker, où un ordinateur inactif ne coûte rien. Les applications et les sessions de longue durée restent alors actives. Cela concerne le coût, pas la mémoire. Sur un petit VPS, laissez le minuteur activé. Sinon, chaque ordinateur que vous aurez démarré, ainsi que chaque navigateur qu’il contient, continuera de fonctionner.
L’espace disque compte également. L’image du sandbox, les modules Node et le volume Postgres partagent le même disque. 40 GB constitue donc un point de départ raisonnable.
Épinglez une version avant le clonage
Rakazo évolue rapidement et main n’est pas une release. Au 9 novembre 2026, v0.8.0, publiée le 4 novembre 2026, est la release marquée Latest. Ce guide reste épinglé sur v0.3.5, publiée le 25 octobre 2026.
git clone https://github.com/elie222/rakazo.git
cd rakazo
git checkout f31e3c0699f086d663637c4107858c238a086fb3
git log -1 --format='%H %ci'C’est le commit pointé par v0.3.5. Épinglez le commit plutôt que la branche ou le tag. Une branche change au prochain git pull, et un tag est un libellé modifiable qu’un maintainer peut faire pointer ailleurs. Aucun des deux ne permet donc d’identifier un arbre auquel vous pourrez revenir. L’identifiant d’un commit ne change pas. Notez le vôtre avec les autres informations de votre serveur, car lorsqu’une mise à niveau casse l’installation, la solution rapide consiste à git checkout <old commit> puis à reconstruire, ce qui ne fonctionne que si vous savez quel commit fonctionnait. Le README épinglé qualifie Rakazo de beta ; cette précision vaut donc le faible effort nécessaire. Un projet qui publie régulièrement des releases maîtrisées peut être maintenu sur un tag publié, comme le fait 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 --versionpackage.json déclare "engines": { "node": "^22.22.2 || ^24.0.0 || >=26.0.0" } et "packageManager": "pnpm@9.15.0". node -v doit donc afficher v22.22.2 ou une version 22.x ultérieure, n’importe quelle version de v24, ou v26 et une version ultérieure. Une version de v22 antérieure à 22.22.2 ne respecte pas cette plage, et le README indique explicitement que Node.js 23.x et 25.x ne sont pas pris en charge. Installez une version de Node prise en charge depuis NodeSource ou nvm. Corepack est fourni avec Node 22 et 24 ; avec Node 26 et les versions ultérieures, installez-le d’abord avec npm install -g corepack. Activez ensuite pnpm :
corepack enable
corepack prepare pnpm@9.15.0 --activateDocker Engine et le plugin compose couvrent le reste. La documentation sur l’auto-hébergement demande Docker Engine 26 ou une version ultérieure, l’API 1.45 ou une version ultérieure pour les sous-chemins de volumes du répertoire personnel du bot, ainsi que curl et OpenSSL. Votre utilisateur doit également pouvoir accéder au daemon. Si docker ps répond permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock, ajoutez votre utilisateur au groupe docker et ouvrez un nouveau shell de connexion. Sachez d’abord ce que cela permet : être membre de docker équivaut à disposer des privilèges 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.
Configurez .env, puis démarrez Postgres
cp .env.example .env
chmod 600 .envPlusieurs valeurs doivent être modifiées avant tout démarrage. .env.example contient par défaut 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 et SANDBOX_SUPERVISOR_TOKEN=replace-with-32-plus-character-supervisor-token, et laisse POSTGRES_PASSWORD et POSTGRES_APP_PASSWORD vides. Tous ces placeholders sont publiés dans le repository : un déploiement qui en conserve un utilise donc un secret que n’importe qui peut lire. Attribuez une valeur aléatoire distincte à chacun. ENCRYPTION_KEY doit contenir 64 caractères hexadécimaux aléatoires, exactement ce que openssl rand -hex 32 affiche. Les autres secrets doivent contenir au moins 32 caractères : exécutez donc la ligne base64 une fois pour chacun. Pour les deux mots de passe Postgres, la documentation self-host demande des valeurs compatibles avec les URL. La dernière ligne vous en fournit ; exécutez-la donc une fois pour chacun. La base de données possède deux comptes. DATABASE_MIGRATION_URL contient par défaut postgres://rakazo:REPLACE_WITH_POSTGRES_PASSWORD@127.0.0.1:5433/rakazo, le propriétaire qui exécute les migrations, et DATABASE_URL contient postgres://rakazo_app:REPLACE_WITH_POSTGRES_APP_PASSWORD@127.0.0.1:5433/rakazo, le compte utilisé par l’application. Ce compte n’a pas de droits de superuser et est soumis à la sécurité au niveau des lignes. Placez chaque mot de passe dans sa propre URL. pnpm db:migrate crée le compte rakazo_app avec le mot de passe que vous avez défini.
openssl rand -base64 48
openssl rand -hex 32
openssl rand -hex 24Démarrez ensuite la base de données seule et exécutez les migrations.
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:buildpnpm 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, qui doit afficher une ligne.
Le fichier compose de base ne publie aucun port Postgres. L’overlay docker-compose.postgres-host.yml utilisé dans cette commande le publie sur 127.0.0.1:5433, limité à la loopback, afin que les outils exécutés sur l’hôte, comme pnpm db:migrate et pnpm dev, puissent y accéder. Conservez cette configuration. Compose refuse de démarrer Postgres sans POSTGRES_PASSWORD dans .env, mais un port Postgres accessible depuis Internet expose la base aux attaques par essais de mots de passe. Le fichier compose de production lit la même variable et ne publie aucun port de base de données.
Le premier lancement
pnpm devCela lance quatre éléments : l’API sur le port 3100, Graphile Worker, l’application web Vite sur 5173 et le sandbox supervisor sur 7091 par défaut. Si ces ports sont déjà utilisés, pnpm dev sélectionne un autre bloc de ports libres et affiche les URL. Avec les ports par défaut, l’application est accessible à http://127.0.0.1:5173 et vous devriez obtenir une page de connexion.
Sur un VPS, vous n’êtes pas connecté directement à cette machine et vous ne devez pas publier le port 5173 pour y accéder. Redirigez plutôt les ports avec SSH (secure shell) depuis votre propre machine.
ssh -L 5173:127.0.0.1:5173 -L 3100:127.0.0.1:3100 you@your-serverSoyez attentif à la différence entre les modes d’exécution. pnpm dev lance Vite sur l’hôte, avec une écoute locale. Le fichier compose de développement publie 127.0.0.1:5173:5173 pour son service web et 127.0.0.1:3100:3100 pour son service api, tous deux uniquement sur loopback ; le même tunnel fonctionne donc pour ces services. Dans le fichier de production, l’application web ne publie aucun port de l’hôte et expose seulement 5173 aux conteneurs de ses propres réseaux. Caddy est le seul service à publier les ports 80 et 443. 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 configurer correctement. SANDBOX_PROVIDER dans .env est docker par défaut, et le checkout épinglé prend aussi en charge Railway, en plus des fournisseurs listés dans la documentation d’auto-hébergement.
dockerest le fournisseur par défaut. Les ordinateurs des bots s’exécutent sous forme de conteneurs sur votre machine, créés à partir de l’imagepnpm sandbox:buildet exécutés sous le contrôle d’un superviseur. Par défaut, les bots d’un workspace partagent un Team Computer, et un bot n’obtient son propre conteneur que sur un Private Computer. Aucun compte E2B n’est nécessaire.e2bexécute les ordinateurs des bots sur E2B et nécessiteE2B_API_KEY. Dansv0.3.5, la factory l’accepte en production lorsque la clé est fournie, sans restrictionNODE_ENV. La documentation d’auto-hébergement le présente comme adapté à la production publique ou multi-utilisateur, car les ordinateurs des bots restent séparés de l’hôte qui exécute votre API et votre base de données.daytona,createosetboatsont d’autres fournisseurs distants. Chacun nécessite sa propre clé :DAYTONA_API_KEY,CREATEOS_SANDBOX_API_KEYouBOAT_API_KEY.railwayexécute les ordinateurs sur Railway et nécessiteRAILWAY_API_TOKENainsi que la sélection explicite deRAILWAY_ENVIRONMENT_IDsur l’API et le worker. Utilisez un projet ou un environnement Railway dédié pour les sandboxes.desktopexécute directement les commandes du bot sur l’hôte de l’API et du worker, comme l’indique la documentation. Dansv0.3.5, l’API et le worker le refusent sauf siNODE_ENVvautdevelopmentoutest, mais.env.examplefournitNODE_ENV=development. Un serveur exécutantpnpm devl’accepte donc toujours. Ne l’activez pas sur un service public ou partagé.fakeest un émulateur destiné uniquement aux vérifications. Ce n’est pas un runtime.nonedémarre le produit sans aucun hôte d’ordinateur.
Prenez cette description au pied de la lettre. En mode desktop, il n’existe aucune frontière d’isolation. Le bot exécute donc les commandes shell avec l’utilisateur 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 d’accéder à vos identifiants. Utilisez-le sur une machine devant laquelle vous êtes assis, ou ne l’utilisez pas. Changer de fournisseur place un conteneur autour de ce chemin d’accès aux pages web, sans le supprimer, et donner à un bot son propre backend de recherche SearXNG couvre la même surface d’injection côté recherche.
docker constitue une véritable frontière entre les bots et votre hôte, mais une frontière faible entre les bots eux-mêmes. Par défaut, ils partagent un Team Computer, et la documentation du runtime des ordinateurs indique que les bots d’une équipe partagent l’utilisateur du système d’exploitation, le workspace, les profils du navigateur ainsi que les accès shell et X11. Elle précise aussi que les répertoires propres à chaque bot organisent le travail, mais ne constituent pas des frontières de sécurité. Un bot d’équipe peut donc lire les fichiers d’un autre bot d’équipe. Un bot qui a besoin de ses propres frontières doit utiliser un Private Computer, que le fournisseur docker exécute comme un conteneur frère distinct sur son propre réseau. Toutefois, le superviseur qui crée ces conteneurs monte /var/run/docker.sock, et la documentation d’auto-hébergement l’indique clairement : l’accès à ce socket équivaut au contrôle de l’hôte Docker. Gardez donc le superviseur privé. .env.example considère SANDBOX_SUPERVISOR_TOKEN comme un identifiant dédié, distinct de BETTER_AUTH_SECRET, requis par les sandboxes Docker en dehors du développement local. Il est fourni avec une valeur fictive que n’importe qui peut lire sur GitHub. Donnez-lui une valeur aléatoire propre. 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 à utiliser une machine qui n’a aucune valeur.
Où sont stockées les clés d’API des modèles ?
La facturation facultative des crédits de modèles de Rakazo reste désactivée tant que les deux secrets Stripe ne sont pas définis. Vous fournissez la clé. .env.example définit PI_DEFAULT_PROVIDER=openrouter, donc OPENROUTER_API_KEY est l’emplacement habituel, et les clés des fournisseurs utilisent le même paramètre.
Conservez la clé dans .env et ne la placez dans aucun fichier que vous committez. Les deux commandes compose du dépôt transmettent --env-file .env. Les valeurs parviennent donc aux conteneurs sans jamais être écrites dans un fichier YAML suivi par git. Vous pouvez également laisser OPENROUTER_API_KEY vide et connecter un modèle dans l’application après l’inscription. C’est une raison supplémentaire pour laquelle ENCRYPTION_KEY doit avoir une vraie valeur aléatoire plutôt que la valeur fictive fournie par défaut.
Définissez une limite de dépense sur la clé auprès du fournisseur avant qu’un bot ne l’utilise. Un bot qui boucle est un bot qui dépense. Rakazo fournit également MAX_TOOL_CALLS_PER_TURN : définissez un entier positif pour arrêter progressivement un tour qui dépasse son budget d’appels d’outils, tout en produisant un dernier message de l’assistant. Si le paramètre n’est pas défini, est vide ou vaut 0, aucune limite ne s’applique. Ce paramètre compte les appels d’outils, pas l’argent dépensé. Il ne remplace donc pas la limite de dépense du fournisseur. Donnez à cette clé un nom distinct afin de pouvoir la révoquer seule. Si vous configurez ce système pour une équipe plutôt que pour vous-même, consultez la passerelle unique de OneCLI devant les agents de toute l’équipe. C’est une autre réponse au même problème, car les clés des fournisseurs sont conservées au même endroit au lieu d’être dupliquées pour chaque personne.
Passer du mode de développement à une installation 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 (sécurité de la couche transport) qu’il obtient automatiquement. Caddy est le seul service qui publie des ports. Il utilise E2B par défaut pour les ordinateurs des bots. Une surcouche optionnelle, infra/compose/docker-compose.prod.docker.yml, exécute à la place des ordinateurs Docker locaux dans la même stack. La documentation avertit que le superviseur qu’elle ajoute dispose de privilèges équivalents à ceux de root sur l’hôte.
sudo --preserve-env=SSH_CONNECTION 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/healthCréez un compte deploy avec authentification par clé uniquement et vérifiez que vous pouvez vous y connecter avant d’exécuter le script. harden-host.sh désactive l’authentification SSH par mot de passe et la connexion root, limite le débit des connexions SSH, ajoute les autorisations SSH, HTTP et HTTPS dans UFW (pare-feu non complexe) tout en conservant les règles existantes pour les réseaux privés, puis active fail2ban, les mises à jour de sécurité automatiques, AppArmor et les règles d’audit. Il refuse de s’exécuter sans SSH_CONNECTION, ce qui explique pourquoi la commande le transmet via sudo. Il annule aussi la modification du pare-feu si vous ne la confirmez pas depuis une nouvelle session SSH dans les trois minutes. Lisez-le avant de l’exécuter, car il modifie votre mode de connexion et recharge SSH. Gardez la console de votre fournisseur ouverte jusqu’à ce qu’une nouvelle connexion SSH réussisse.
Le .env de production nécessite davantage que celui de développement. La documentation consacrée à l’auto-hébergement indique ce minimum, ainsi que les secrets.
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>
POSTGRES_APP_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>Pointez un enregistrement A vers le serveur avant ce premier up. Caddy demande un certificat pour le nom indiqué dans RAKAZO_HOST. Ce nom doit résoudre vers cette machine, et le port 80 pour la validation HTTP ou le port 443 pour la validation TLS-ALPN doit être accessible depuis l’extérieur. Les deux challenges sont activés par défaut. Fermer uniquement le port 80 n’empêche donc pas l’émission du certificat via le port 443.
Conservez SIGNUP_ALLOWLIST configuré avec votre propre adresse dès le début. .env.example fournit SIGNUPS_ENABLED=true, et les deux paramètres sont lus dans l’environnement à chaque démarrage de l’API. Une instance accessible par un nom public, avec les inscriptions activées et sans allowlist, accepte donc les inscriptions de toute personne qui la trouve. Une allowlist non vide est appliquée à chaque démarrage et remplace la liste enregistrée. L’inscription via une allowlist nécessite la vérification de la boîte aux lettres, y compris pour le premier compte. Configurez donc l’envoi des e-mails avant de vous inscrire. Sans e-mail, la documentation recommande de démarrer avec SIGNUPS_ENABLED=false, puis de créer votre compte à l’aide de la commande d’amorçage côté serveur indiquée. Cette commande crée un compte vérifié ordinaire, sans privilèges sur le serveur. Commencez par l’allowlist. Vous pourrez l’assouplir plus tard si nécessaire. Si vous exécutez déjà plusieurs services sur la même machine et préférez gérer une seule liste de personnes plutôt qu’une allowlist par application, placer une instance d’Authentik devant ces services déplace cette décision vers le proxy. Authentik reste toutefois devant les comptes Better Auth propres à Rakazo et ne les 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 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 plus importants lorsqu’une stack doit rester sans intervention pendant plusieurs mois.
Sauvegardes
Dans cette configuration, Postgres et le répertoire data/ contiennent les données de l’instance. La restauration nécessite également ENCRYPTION_KEY et toutes les clés maîtresses de contenu configurées. Conservez donc des copies hors du serveur.
./scripts/backup.sh
./scripts/restore.sh backups/BACKUP_TIMESTAMPbackup.sh effectue un dump de Postgres et archive data/. restore.sh fonctionne avec la stack Compose de développement, sur une base de données vide et avec les services de l’application arrêtés. Il ne lit pas les fichiers de sauvegarde de production. 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. Il écrit un dump vérifié et une archive des données de l’application dans /var/backups/rakazo. Il conserve par défaut jusqu’à trois instantanés vérifiés, nombre défini par RAKAZO_BACKUP_KEEP, dans une limite de 50 GiB définie par RAKAZO_BACKUP_MAX_GB. Il supprime les instantanés partiels et l’historique excédentaire avant chaque exécution. La rotation est donc automatique. Il peut également chiffrer chaque sauvegarde avec age pour les destinataires publics que vous indiquez dans /etc/rakazo/backup.env. Le serveur écrit ainsi des sauvegardes qu’il ne peut pas lire. Générez cette paire de clés sur une machine que vous contrôlez et conservez la clé privée hors du serveur. Sans destinataires, la sauvegarde reste en texte clair et un avertissement est journalisé. Après la première sauvegarde chiffrée, une exécution sans destinataires échoue, sauf si vous autorisez explicitement le texte clair avec RAKAZO_BACKUP_ALLOW_PLAINTEXT=1. Une sauvegarde stockée sur le même disque que la base de données n’est pas une sauvegarde. Copiez-la donc 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. Soit le conteneur Postgres n’est pas démarré, soit il est démarré mais pas encore prêt, soit il a été lancé sans la surcharge docker-compose.postgres-host.yml, qui publie le port 5433 sur l’hôte. Exécutez docker compose --env-file .env -f infra/compose/docker-compose.yml ps et vérifiez que le service postgres est indiqué comme sain, car le fichier Compose effectue un health check toutes les trois secondes. Si le conteneur redémarre en boucle, consultez ses journaux : la stack Compose verrouillée refuse de démarrer sur un ancien volume Postgres 16 tant qu’il n’a pas été migré vers Postgres 18. 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 le port 5433, le plus souvent une ancienne stack Rakazo que vous avez oublié d’arrêter. sudo ss -lntp | grep 5433 indique le processus concerné. La surcharge lit le port hôte depuis POSTGRES_HOST_PORT ; vous pouvez donc le modifier, à condition de modifier aussi DATABASE_URL et DATABASE_MIGRATION_URL.
Un bot n’obtient jamais d’ordinateur. Avec SANDBOX_PROVIDER=docker et sans image rakazo/computer:local, rien ne peut démarrer. docker image ls rakazo/computer répond à cette question en une ligne, et pnpm sandbox:build corrige le problème. Si le superviseur ne peut pas accéder au 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 ; 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 supposer que la sandbox a planté.
pnpm install provoque des erreurs difficiles à comprendre. Vérifiez node -v avant toute autre chose. L’espace de travail déclare ^22.22.2 || ^24.0.0 || >=26.0.0 : les versions 23.x, 25.x et toutes les versions 22.x antérieures à 22.22.2 sont donc exclues. Le .npmrc verrouillé définit engine-strict=true ; pnpm install refuse donc une version de Node non prise en charge avec une erreur de moteur/version avant l’exécution du code des dépendances de l’application.
La connexion fonctionne en local, mais pas via le domaine. BETTER_AUTH_URL, WEB_ORIGIN et API_URL doivent tous utiliser la même origine publique que la barre d’adresse, protocole inclus. La présence d’un 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 active.
Mise à jour d’une copie de travail épinglée
La procédure de mise à niveau indiquée dans la documentation d’auto-hébergement pour une stack Compose de production construite à partir de votre copie de travail est courte : récupérez les nouvelles sources, puis reconstruisez et redémarrez l’API, le worker et l’application web. Les migrations s’exécutent au démarrage de l’API, car sa commande de démarrage les applique avant de commencer à traiter les requêtes.
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 webCommencez par effectuer une sauvegarde. Les migrations avancent, et une version bêta ne vous fournit aucun mécanisme de retour fiable. Si votre copie de travail est antérieure au 30 August 2026, ce qui inclut le commit v0.1.0-beta, lisez la note de la documentation sur la migration 20260830200000_space_scope_names_and_user_credentials avant la mise à niveau. Il s’agit d’une bascule coordonnée : arrêtez donc d’abord l’ancienne API et l’ancien worker, puis exécutez le contrôle de la limite de confidentialité de Space indiqué dans la documentation. Si vous effectuez la mise à niveau depuis une copie de travail antérieure à la séparation de la connexion de l’application, définissez POSTGRES_APP_PASSWORD dans .env avant la reconstruction ; le fichier Compose de production refuse de démarrer sans cette variable. Les fichiers Compose de la copie de travail source et de la production utilisent également Postgres 18 : une installation Postgres 16 existante doit suivre la procédure infra/compose/upgrade-postgres.sh de la documentation avant de pouvoir démarrer avec la nouvelle disposition. Lisez les commits compris entre votre SHA épinglé et le nouveau commit avant de les appliquer, car un projet aussi récent renomme parfois des variables d’environnement sans l’annoncer, et une variable manquante se manifeste par un service qui démarre, puis s’arrête. Si vous cherchez encore à déterminer 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 de leur maintien 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 fonctionnent tous en même temps. Avec SANDBOX_PROVIDER=docker, l’ordinateur des bots ajoute un conteneur contenant un bureau graphique, avec un affichage X et un processus Chrome distincts pour chaque bot actif. L’ensemble reste soumis à une limite par défaut de 2 GB de mémoire et de deux CPU. La documentation d’auto-hébergement à v0.3.5 n’indique aucune taille d’hôte. Considérez 4 GB comme le minimum pour le control plane et prévoyez davantage lorsque les bureaux graphiques fonctionnent sur votre machine.
Le fournisseur de desktop sandbox est-il sûr sur un serveur ?
Non. La documentation d’auto-hébergement indique que desktop exécute directement les commandes sur l’hôte de l’API et du worker. Le bot agit donc avec les droits de l’utilisateur qui exécute ce processus et peut accéder à ses fichiers et à ses identifiants. Avec v0.3.5, l’API et le worker le refusent en dehors des modes development et test. En revanche, un serveur exécutant pnpm dev est en mode development et l’accepte. Ne l’utilisez pas sur un serveur public ou partagé. Utilisez docker pour donner à un bot un Private Computer lorsqu’il ne doit pas partager les fichiers avec les autres bots du workspace, ou e2b lorsque plusieurs personnes se connectent.
Quelle version de Rakazo dois-je installer ?
Au 9 novembre 2026, la release la plus récente est v0.8.0, publiée le 4 novembre 2026 et marquée Latest. Pour suivre ce guide, faites un checkout du commit v0.3.5 épinglé, f31e3c0699f086d663637c4107858c238a086fb3, plutôt que de suivre main ou la prerelease d’août v0.1.0-beta. Une branche change sous vous et un tag peut être réorienté ; aucun des deux n’identifie donc un arbre auquel vous pourrez 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 parvient donc aux conteneurs sans être écrite dans un fichier YAML suivi par le contrôle de version. Vous pouvez aussi le laisser vide et connecter un modèle dans l’application après l’inscription. Définissez une limite de dépenses pour la 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 ?
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. Définissez RAKAZO_HOST avec le nom d’hôte public, puis BETTER_AUTH_URL, WEB_ORIGIN et API_URL avec la même origine HTTPS publique. Pour un premier test, vous pouvez ignorer le domaine : exécutez pnpm dev et redirigez le port 5173 avec SSH au lieu de le publier.