Auto-héberger OneCLI avec Docker Compose
Donnez à chaque personne un agent isolé, avec les clés dans une gateway. Installez OneCLI sur un VPS avec Docker Compose et PostgreSQL, en prévoyant 2 GiB par sandbox.
Ce que vous obtenez en auto-hébergeant OneCLI
En auto-hébergeant OneCLI, chaque membre de votre équipe dispose de son propre agent. Chaque agent s’exécute dans son propre sandbox. Les clés d’API sont conservées dans une gateway à laquelle les agents n’ont jamais accès en lecture. L’installation se compose d’une stack Docker Compose avec PostgreSQL, accessible à http://localhost:10254. Prévoyez une machine dédiée. La configuration par défaut documentée limite la mémoire de chaque sandbox d’agent à 2 GiB. Prévoyez donc séparément la mémoire nécessaire à la stack de base et celle réellement utilisée par les agents.
Cette stack comprend huit éléments. Identifier le rôle de chacun facilite la lecture de la suite de ce guide.
- Web dashboard (Next.js), port
10254. Création des agents, chat, modification de la mémoire et des skills, connexions et secrets. - API server, port
10256. Le control plane : base de données, gestion des conversations et files de tâches. - Rust gateway, port
10255. Intercepte les requêtes sortantes des agents et injecte les identifiants. - Runner. Le README le décrit comme le composant qui « démarre, met en pause et récupère les sandbox des agents. Il est uniquement sortant et n’accède jamais à la base de données. »
- Sandbox Supervisor. Le README le décrit comme un composant qui s’exécute « dans chaque sandbox et utilise une interface de harness indépendante du fournisseur, afin de permettre le remplacement du runtime de l’agent. »
- SSH terminator, port
10257. Le README le décrit comme « la porte d’entrée SSH » : il termine les connexions SSH avec des certificats à courte durée de vie émis par l’API, puis relie chaque session au sandbox d’un agent. Il s’exécute avec le même profilrunnerque le runner. - Channel adapter. Un daemon qui connecte une application Slack afin qu’un agent réponde dans les channels et les messages directs sous son propre nom.
- PostgreSQL. Le fichier compose fourni exécute
postgres:18-alpineavec un volumepgdata.
Le nom évoque une CLI, mais le produit est un serveur
OneCLI est une plateforme serveur. Son nom fait penser à un outil en ligne de commande que vous installeriez sur un ordinateur portable. Cette description ne correspond pas au produit présenté dans ce guide. Un client en ligne de commande distinct existe bien dans le dépôt onecli/onecli-cli. Il achemine le trafic d’un agent de codage local via une gateway. Ce que vous déployez ici est une application web multi-utilisateur : un système de comptes avec des organisations et des invitations, une base de données contenant les conversations et les secrets, ainsi qu’un runner qui démarre des conteneurs.
Le modèle par personne constitue le cœur de la conception. Le README indique : « Vous créez un agent par personne, vous donnez à chaque agent les accès dont il a besoin, puis il fonctionne dans un sandbox, via une gateway qui injecte les identifiants et applique votre politique. » Chaque agent possède son propre système de fichiers et son propre shell, sa propre page de conversation, une mémoire conservée par la plateforme et des skills que vous écrivez une seule fois. La gestion des identifiants fonctionne à l’inverse de la configuration habituelle. Au lieu de copier une clé d’API dans l’environnement de chaque personne, vous stockez la clé une seule fois et vous l’accordez aux agents autorisés à l’utiliser.
Prérequis du serveur
- Docker, avec le plugin Compose en version 2.24.0 ou ultérieure. Le fichier Compose fourni utilise des mappings
env_filefacultatifs avecrequired: false, pris en charge par Docker à partir de la version 2.24.0. Ses commentaires de migration indiquent que la version minimale 2.19 correspond à la prise en charge des dépendances à exécution unique avecup --wait, mais cela ne couvre pas les fichiers d’environnement facultatifs utilisés par le fichier. - De la mémoire, qui constitue la véritable contrainte. Consultez la section sur le dimensionnement ci-dessous avant de choisir une offre.
- Les ports loopback
10254,10255,10256,10257et5432doivent être libres. Le port10257est le point d’entrée SSH, qui démarre avec le profilrunneractivé par ce guide.
Vous n’avez pas besoin d’installer PostgreSQL vous-même : le fichier Compose l’exécute comme un service. L’assistant de configuration ci-dessous nécessite Node.js et pnpm sur l’hôte. Le travail sur le code utilise également mise pour figer la toolchain, notamment Rust pour la passerelle.
Combien de sandboxes d’agent votre VPS peut-il héberger ?
La documentation du runner fournit des chiffres concrets. Chaque sandbox est limitée à 2048 MB de mémoire (RUNNER_SANDBOX_MEMORY_MB), un CPU (RUNNER_SANDBOX_CPUS) et 512 processus (RUNNER_SANDBOX_PIDS). La limite de concurrence est de 4 (RUNNER_MAX_SANDBOXES), et la documentation recommande environ 10 GiB de mémoire libre en plus de la stack de base pour respecter cette limite.
Les données de ce graphique
[
{
"plan": "2 GB box",
"ram_gb": 2,
"sandbox_slots": 0
},
{
"plan": "4 GB box",
"ram_gb": 4,
"sandbox_slots": 1
},
{
"plan": "8 GB box",
"ram_gb": 8,
"sandbox_slots": 3
},
{
"plan": "16 GB box",
"ram_gb": 16,
"sandbox_slots": 7
},
{
"plan": "32 GB box",
"ram_gb": 32,
"sandbox_slots": 15
}
]Ces nombres de slots résultent d’un calcul, pas d’un benchmark : mémoire totale, moins environ 2 GB supposés pour PostgreSQL et les autres services persistants, divisée par la limite de 2 GiB par sandbox. Sur cette base, le 2 GB box prévoit le budget nécessaire pour 0 sandboxes à leur limite mémoire maximale ; zéro signifie qu’aucun budget ne permet d’atteindre cette limite dans ces hypothèses, et non que Docker refuse de démarrer un agent. Un 16 GB box laisse de la marge pour 7, soit largement plus que la limite par défaut de quatre et que les environ 10 GiB de mémoire libre demandés par la documentation du runner. Le 32 GB box vous permet d’atteindre 15. Pour en exécuter plus de quatre simultanément, vous devez également augmenter RUNNER_MAX_SANDBOXES.
Deux éléments modifient ce calcul. Une sandbox qui exécute un processus en arrière-plan ne se met jamais en veille. Elle conserve donc son slot en permanence. Vous devez dimensionner RUNNER_MAX_SANDBOXES pour une charge soutenue, et non pour la minute la plus chargée. La plateforme impose toutefois une limite : par défaut, chaque runner conserve au maximum RUNNER_MAX_SANDBOXES moins une sandbox maintenue active (jamais moins d’une). Vous pouvez remplacer cette valeur avec MAX_HELD_AWAKE_SANDBOXES via l’API. Au-delà de cette limite, le runner supprime la sandbox inactive depuis le plus longtemps et signale son processus surveillé comme perdu. L’utilisation de la mémoire et du CPU dépend de la charge. Chaque sandbox est limitée à un CPU. Quatre agents actifs peuvent donc utiliser quatre cœurs. En revanche, la limite mémoire de 2 GiB est un plafond et non une réservation : quatre agents inactifs mais maintenus actifs ne consomment pas automatiquement 8 GiB.
Paramètres du runner que vous pouvez modifier
RUNNER_MAX_SANDBOXES(par défaut4) : nombre de sandboxes exécutées simultanément.RUNNER_SANDBOX_MEMORY_MB(par défaut2048) : limite mémoire par sandbox.RUNNER_SANDBOX_CPUS(par défaut1) : limite CPU par sandbox.RUNNER_SANDBOX_PIDS(par défaut512) : limite de processus par sandbox.RUNNER_NETWORK_INTERNAL(par défauttrue) : conserve le réseau de la sandbox sans route vers l’extérieur. Laissez ce paramètre activé.RUNNER_SANDBOX_NETWORK(par défautonecli-sandboxes) : réseau auquel les sandboxes se connectent.RUNNER_RECONCILE_SECONDS(par défaut60) : fréquence à laquelle le runner réconcilie l’état.RUNNER_ORPHAN_GRACE_SECONDS(par défaut3600) : ancienneté à partir de laquelle les conteneurs et volumes orphelins sont détruits.RUNNER_AGENT_IMAGE: remplace l’image de la sandbox, qui suit sinonONECLI_VERSION.
Installer OneCLI avec Docker Compose
La procédure brute du document officiel d’auto-hébergement écrit trois secrets dans docker/.env, à côté du fichier Compose. Elle omet le token du runner, le groupe du socket Docker et les identifiants SSH requis par les services qu’elle active. Exécutez donc l’assistant de configuration avant de démarrer la stack.
git clone https://github.com/onecli/onecli.git && cd onecli/docker
cat > .env <<EOF
SECRET_ENCRYPTION_KEY=$(head -c 32 /dev/urandom | base64)
GATEWAY_INTERNAL_SECRET=$(head -c 32 /dev/urandom | base64)
BETTER_AUTH_SECRET=$(head -c 32 /dev/urandom | base64)
COMPOSE_PROFILES=runner
EOF
chmod 600 .env
cd ..
pnpm install
pnpm run setup
cd docker
docker compose up -d --waitLisez ce bloc avant de l’exécuter. Le marqueur heredoc n’est pas placé entre guillemets. Votre shell exécute donc chaque head -c 32 /dev/urandom | base64 et écrit le résultat au lieu du texte littéral. SECRET_ENCRYPTION_KEY est la clé AES-256-GCM utilisée pour chaque secret de la base de données. GATEWAY_INTERNAL_SECRET authentifie la gateway auprès de l’API. BETTER_AUTH_SECRET signe les cookies de session. COMPOSE_PROFILES=runner est la ligne la plus importante, car le service runner se trouve derrière un profil Compose. Si vous l’omettez, la stack démarre correctement, mais aucun sandbox d’agent ne démarre.
--wait attend que les services soient en cours d’exécution ou sains, et que la dépendance de migration se termine correctement. Une sortie différente de zéro est donc votre premier signal qu’un problème existe. Vérifiez ensuite ce qui a réellement démarré.
docker compose ps
docker compose logs migrationsFigez la version. ONECLI_VERSION définit le tag de tous les services en une seule fois. L’image du sandbox d’agent le suit également, sauf si RUNNER_AGENT_IMAGE pointe vers un autre emplacement. Utilisez uniquement le numéro de version. Les tags d’image publiés ne contiennent pas le préfixe v. Au 1 novembre 2026, la version actuelle est v2.17.0, publiée le 31 octobre 2026. Ajoutez-la au même fichier, puis utilisez la procédure de mise à niveau documentée afin que les sandbox en cours d’exécution utilisent eux aussi cette image.
echo 'ONECLI_VERSION=2.17.0' >> .env
cd ..
pnpm run setup --upgrade
cd dockerUn installateur existe également : curl -fsSL https://onecli.sh/install | sh. Il écrit sa configuration dans ~/.onecli/.env et effectue le même travail. Il définit ONECLI_VERSION=latest pour sa propre exécution. Cette valeur remplace une version figée uniquement dans le fichier .env. La méthode Compose permet de lire chaque fichier avant toute exécution. C’est aussi celle à utiliser sur une machine qui héberge déjà d’autres stacks Compose. La configuration récupérée plus haut se met à niveau avec pnpm run setup --upgrade. Cette méthode nécessite Node.js et pnpm sur l’hôte. Modifier le code lui-même ajoute aussi mise et Rust pour la gateway. Elle convient donc aux personnes qui souhaitent modifier OneCLI. Pour Kubernetes, la version v2.11.0, publiée le 8 octobre 2026, a ajouté un chart Helm. Le chart actuel exécute les sandbox d’agents sous forme de Jobs avec des volumes persistants, sans daemon Docker. Il documente également les secrets requis, la base de données et la configuration du routage.
Accéder au tableau de bord depuis votre ordinateur portable
Chaque port publié dans le fichier compose fourni est lié à ${ONECLI_BIND_HOST:-127.0.0.1}. Sur un VPS, cela signifie que le tableau de bord fonctionne, mais qu’aucun accès extérieur au serveur ne peut l’atteindre. Ce comportement par défaut est correct. Conservez-le et créez un tunnel :
ssh -N -L 10254:127.0.0.1:10254 you@your-serverOuvrez ensuite http://localhost:10254 sur votre ordinateur portable. Le trafic passe par la connexion SSH. Le tableau de bord n’est donc pas exposé en clair sur Internet et vous n’avez pas besoin d’ouvrir un port supplémentaire dans le firewall.
Définir ONECLI_BIND_HOST=0.0.0.0 publie le tableau de bord en HTTP non chiffré et publie également PostgreSQL, avec le mot de passe par défaut du fichier compose, onecli, sauf si vous définissez POSTGRES_PASSWORD. Cela publie aussi le point d’entrée SSH sur le port 10257, un service qui monte le socket Docker. Si plusieurs personnes doivent accéder au tableau de bord, placez un reverse proxy avec TLS (transport layer security) devant celui-ci et laissez l’adresse de bind inchangée. Définissez ONECLI_EXTERNAL_URL avec son URL HTTPS et utilisez la configuration de reverse proxy du projet amont. Elle achemine les chemins du tableau de bord, de l’API et de la gateway vers les services correspondants. Un proxy ne suffit pas à lui seul à empêcher les accès non autorisés. La documentation d’auto-hébergement précise que l’inscription est ouverte par conception et qu’aucun réglage ne permet de la désactiver : toute personne qui peut atteindre le tableau de bord peut créer un compte. Ce compte obtient sa propre organisation. Seule l’adhésion à votre organisation nécessite une invitation. La documentation recommande de conserver le tableau de bord derrière la limite de votre réseau. Si ce proxy sert déjà de frontal à vos autres applications auto-hébergées, le forward auth via une couche de single sign-on auto-hébergée place le tableau de bord derrière le login déjà utilisé par votre équipe. La suppression d’un utilisateur à un seul endroit ferme donc également cet accès.
Créer le premier compte, puis accorder une clé de modèle
Ouvrez le tableau de bord et créez immédiatement votre compte. Chaque nouveau compte reçoit sa propre organisation, et vos collaborateurs rejoignent la vôtre sur invitation. L’inscription reste ensuite ouverte, ce qui constitue une raison supplémentaire de placer le tableau de bord derrière le tunnel ou un proxy authentifié. Si vous effectuez une mise à niveau depuis une release antérieure à l’introduction des connexions, inscrivez-vous immédiatement : la documentation d’auto-hébergement indique que les données existantes sont associées au premier compte qui s’inscrit. Sur un hôte accessible, ce compte doit donc être le vôtre.
Enregistrez ensuite une clé de modèle avant de créer un agent. Un agent hébergé a besoin d’une clé de modèle qui lui est accordée, et l’ordre est important : enregistrez la clé dans le tableau de bord, accordez-la à l’agent, puis démarrez seulement la conversation. Si vous n’accordez pas la clé, la sandbox ne se lance jamais. L’agent répond dans le thread qu’il a besoin d’une clé de modèle.
Accordez les droits de manière restrictive. Chaque agent reçoit uniquement les droits que vous lui accordez, et la gateway les applique à chaque requête. Un agent qui lit un dépôt n’a donc aucun accès à la clé de votre fournisseur de paiement. La même liste de droits vous permet également de maîtriser les dépenses. Un agent individuel capable d’appeler n’importe quel modèle dont vous disposez génère une facture individuelle. Il est donc utile de lire comment limiter ce qu’un agent peut dépenser en appels de modèles avant d’en distribuer dix.
Comment la gateway garde les clés hors des agents
La gateway est un proxy HTTPS écrit en Rust, qui écoute sur le port 10255. Le client HTTP d’un agent est configuré pour l’utiliser, et l’agent transporte un identifiant factice au lieu d’un identifiant réel. La gateway compare la requête sortante aux autorisations de cet agent, déchiffre le secret réel, le remplace dans la requête, puis la transmet. Les secrets sont stockés dans PostgreSQL, chiffrés avec AES-256-GCM (advanced encryption standard, 256-bit, Galois/counter mode), et déchiffrés uniquement au moment de la requête. Chaque appel est journalisé avec l’identité de l’agent et sa cible. Vous disposez ainsi d’une piste d’audit impossible à obtenir lorsque les clés sont présentes dans les profils shell de dix personnes.
Deux mécanismes déterminent la manière de déployer cette solution.
- L’interception HTTPS est une attaque de type man-in-the-middle. La gateway génère une autorité de certification locale, l’agent lui fait confiance, puis la gateway termine la connexion TLS de l’agent et en ouvre une nouvelle vers le service upstream. C’est pourquoi un agent dont le client HTTP ne fait pas confiance à l’autorité de certification de la gateway échoue avec une erreur de vérification du certificat, et non avec une erreur d’authentification.
- L’agent s’identifie avec un en-tête
Proxy-Authorization. Sur une même machine, lorsque les agents et la gateway partagent un réseau Docker interne, cet en-tête ne traverse jamais un réseau que vous ne contrôlez pas. Si vous dirigez un agent situé sur une autre machine vers la gateway, protégez la connexion avec un VPN ou un transport TLS, car cet en-tête est un bearer token ; upstream recommande un VPN pour le port du proxy CONNECT brut.
Le compromis est clair : la gateway lit en clair, par conception, chaque requête envoyée par vos agents. C’est le processus le plus sensible de la machine. Sécurisez son hôte en conséquence et limitez le nombre de personnes pouvant s’y connecter en utilisant des utilisateurs Linux aux privilèges minimaux.
Pourquoi le runner n’a besoin d’aucun port entrant
Le runner fonctionne uniquement en sortie. Sa documentation précise : « il n’expose aucun port accessible depuis l’extérieur. Un laptop, un homelab ou un VPC derrière un NAT fonctionnent donc sans ingress, sans tunnel et sans terminaison TLS ». NAT signifie traduction d’adresses réseau. C’est ce que fait un routeur domestique. Le runner ouvre une connexion vers le control plane et y récupère le travail. Il n’y a donc aucun port à rediriger ni à ouvrir.
Cette conception est utile sur le réseau de sandbox. Le fichier compose définit un second réseau marqué internal: true. Dans Docker, cela signifie qu’il n’a aucune connectivité réseau externe. Les sandbox le rejoignent. La gateway est connectée aux deux réseaux. C’est donc le seul point de sortie. La documentation du runner l’explique clairement : « un réseau internal auquel la gateway est connectée sur deux interfaces transforme la sortie exclusivement par la gateway en une limite effective, et non en une simple recommandation ». Un agent ne peut pas contourner la gateway en ouvrant directement une connexion vers une adresse externe. La policy de la gateway détermine toujours quelles requêtes elle autorise.
Vérifiez-le sur votre propre machine au lieu de vous fier au paragraphe ci-dessus.
docker network ls
docker network inspect onecli-sandboxes | grep -i internalVous devez voir "Internal": true. Si le résultat est false, le contrôle des connexions sortantes est désactivé et la gateway redevient une simple recommandation. Utilisez le nom du réseau de sandbox affiché par docker network ls, car onecli-sandboxes n’est que la valeur par défaut.
Quelle est la robustesse du sandbox OneCLI ?
Lisez cette section attentivement, car le terme « sandboxé » occupe une place importante dans la description du projet, alors que le mécanisme est documenté dans la documentation du runner et dans le code du backend.
Le README indique que chaque agent dispose de « son propre sandbox isolé, avec un système de fichiers et un shell », et présente le Sandbox Supervisor comme le composant qui « s’exécute dans chaque sandbox, en utilisant une interface de harness indépendante du fournisseur afin de permettre le remplacement du runtime de l’agent ». Aucune de ces phrases ne précise en quoi consiste l’isolation. La documentation du runner le précise : le backend par défaut est Docker (RUNNER_BACKEND=docker), et un sandbox est un conteneur Docker avec une limite de mémoire, une limite CPU et une limite du nombre de processus, connecté au réseau interne. Le code prévoit un point d’extension pour d’autres backends. Le code actuel du runner implémente également un backend Kubernetes, utilisé par le chart Helm pour les Jobs de sandbox et les volumes persistants. Dans l’installation Compose de ce guide, un sandbox est un conteneur Docker.
La documentation du runner décrit maintenant la frontière Docker : l’agent s’exécute sous node, avec no-new-privileges, toutes les capabilities Linux supprimées et le profil seccomp par défaut de Docker. Le backend ne monte dans le sandbox que le home persistant de l’agent. Retenez donc l’interprétation stricte. Les limites sont des limites de ressources. Le réseau interne constitue un véritable contrôle des sorties réseau. L’isolation entre un agent et votre hôte repose sur ces contrôles de conteneur, et un conteneur partage le kernel de l’hôte.
Il faut également tenir compte d’un autre fait. Le service runner monte /var/run/docker.sock, car c’est ainsi qu’il crée les sandboxes. L’accès au socket d’un daemon Docker rootful équivaut à un accès root sur l’hôte, car toute personne capable d’appeler cette API peut démarrer un conteneur en y montant le système de fichiers de l’hôte. Le runner Docker fourni utilise ce socket. Il en résulte que le processus runner est aussi sensible que le gateway. Le terminateur SSH monte le même socket afin de pouvoir exécuter des commandes dans les conteneurs de sandbox, et les commentaires du fichier Compose indiquent eux-mêmes que ce montage équivaut à un accès root sur l’hôte. Laissez donc le port 10257 lié à loopback, sauf si vous avez une raison de l’ouvrir.
Considérez la frontière du kernel partagé avec prudence. En pratique, cela implique trois habitudes.
- Exécutez OneCLI sur une machine qui ne fait rien d’autre. Aucun service de production sans rapport, aucune base de données partagée, aucune donnée d’une autre équipe.
- Supposez qu’un agent ayant obtenu l’exécution de code arbitraire dans son sandbox puisse atteindre l’hôte, et rendez cette situation gérable grâce à des sauvegardes conservées hors de la machine.
- Lisez
apps/runner/srcou interrogez l’équipe amont avant d’affirmer à un collègue que l’agent est contenu.
Pour voir à quoi ressemble une frontière documentée et connaître les questions à poser à l’équipe amont, comparez ce texte à ce à quoi ressemble une véritable frontière de sandbox d’agent. La question est de savoir si le mécanisme documenté couvre les menaces que vous devez bloquer.
La séparation des licences et les vérifications à effectuer avant de déployer
Le cœur de OneCLI est sous licence Apache-2.0, et son auto-hébergement en production est autorisé. Les répertoires nommés ee/ sont couverts par une licence OneCLI Enterprise distincte : leur utilisation est gratuite pour le développement, les tests et l’évaluation, mais un abonnement est requis en production. Les notes de version de v2.0.1, datées du 18 August 2026, mentionnent la restauration d’un fichier de licence Apache-2.0 détectable par GitHub. Le badge affiché sur la page du dépôt a donc changé récemment. Vérifiez le tag que vous allez réellement déployer plutôt qu’un résumé rédigé à une autre date.
cd onecli && find . -type d -name ee -not -path '*/node_modules/*'Tout ce qui se trouve sous ces chemins appartient à la partie commerciale. Si une fonctionnalité dont vous prévoyez de dépendre s’y trouve, vérifiez son coût avant de bâtir un processus autour d’elle.
Mises à niveau, migrations et le seul fichier que vous ne pouvez pas perdre
Les mises à niveau doivent actualiser les images des services et l’image distincte de l’agent, puis redémarrer les sandboxes en cours d’exécution. Un service de migration exécuté une seule fois démarre avant l’API à chaque up. Si une migration échoue, la stack refuse de démarrer au lieu de fonctionner avec un schéma partiellement migré. C’est le comportement attendu, car une mise à niveau échouée se manifeste alors par une indisponibilité plutôt que par une corruption silencieuse. docker compose logs migrations en explique la raison.
Une étape est facile à oublier. Le document d’auto-hébergement déconseille d’effectuer la mise à niveau avec un simple docker compose pull && docker compose up -d, car l’image de sandbox de l’agent n’est pas un service Compose. Elle est définie par la valeur RUNNER_AGENT_IMAGE sur le runner. docker compose pull ne la voit donc jamais, et les agents hébergés peuvent conserver une ancienne image de sandbox sans aucun avertissement. Mettez à jour le checkout, déplacez le pin, puis exécutez l’outil de mise à niveau documenté. Celui-ci récupère l’image de sandbox et redémarre les sandboxes en cours d’exécution.
cd onecli
git pull
sed -i 's/^ONECLI_VERSION=.*/ONECLI_VERSION=2.17.0/' docker/.env
pnpm install
pnpm run setup --upgrade
cd docker
docker compose logs migrationsRemplacez 2.17.0 par la release vers laquelle vous migrez. Le redémarrage des sandboxes interrompt le travail en cours. L’espace de travail persistant de chaque agent est conservé.
Si vous avez utilisé le script d’installation, exécutez de nouveau ce script au lieu de récupérer les éléments manuellement. Le fichier Compose reste ainsi cohérent avec les images qu’il référence. Exportez d’abord ONECLI_VERSION si vous voulez une release précise, car le script remplace un pin conservé uniquement dans son fichier .env.
Sauvegardez la base de données, la configuration et les volumes contenant les espaces de travail des agents. PostgreSQL contient les agents, les conversations, la mémoire et les secrets chiffrés. Le fichier docker/.env contient SECRET_ENCRYPTION_KEY. Sans cette clé, les secrets chiffrés sont illisibles, même si le reste de la base de données est restauré. Le /workspace de chaque agent se trouve sur un volume persistant distinct et nécessite sa propre sauvegarde.
cd onecli/docker
docker compose exec -T postgres pg_dump -U onecli onecli | gzip > ~/onecli-db.sql.gz
install -m 600 .env ~/onecli-env.backupConservez ces copies et les sauvegardes des espaces de travail hors de la machine. La procédure est la même que pour toute stack Compose avec état. Si vous sauvegardez et mettez à niveau une stack Docker Compose selon un calendrier, ajoutez-y les volumes de la base de données, de la configuration et des espaces de travail, puis n’y pensez plus.
Lorsque cela ne fonctionne pas
- La stack ne devient jamais healthy et
docker compose up -d --waitse termine avec un code différent de zéro. Consultez d’aborddocker compose logs migrations, car l’API attend délibérément que ce service soit disponible. - Un agent reste inactif et aucun sandbox n’apparaît. Vérifiez que
COMPOSE_PROFILES=runnerfigure dansdocker/.envet quedocker compose psrépertorie un runner. Vérifiez ensuite que l’agent dispose d’une model key accordée, car les sandboxes ne se lancent pas sans elle. - Il ne reste plus de slots.
RUNNER_MAX_SANDBOXESutilise 4 par défaut. Un sandbox qui exécute un processus en arrière-plan conserve son slot jusqu’à son éviction lorsque la limite de maintien actif est atteinte.docker psindique ce qui est réellement actif. - La stack ne démarre pas et Docker signale qu’un port est déjà utilisé. Lorsque le profil
runnerest activé, la porte d’accès SSH utilise10257en plus des quatre autres ports. - Les conteneurs disparaissent ou l’hôte devient très lent. Vérifiez une éventuelle saturation de la mémoire avec
dmesg -T | grep -i oom. La limite mémoire par défaut permet à un sandbox d’utiliser jusqu’à 2048 MB. - Les appels HTTPS d’un agent échouent avec des erreurs de vérification du certificat, et non avec des erreurs d’authentification. Son client HTTP ne fait pas confiance à l’autorité de certification de la gateway.
- D’anciens conteneurs ou volumes restent présents après la suppression d’un agent. Le runner effectue une reconciliation toutes les 60 secondes et détruit les orphelins âgés de plus de
RUNNER_ORPHAN_GRACE_SECONDS, soit 3600 par défaut. Attendez donc une heure avant de conclure à une fuite.
Est-ce la bonne solution pour vous ?
Le test d’adéquation est simple. OneCLI est pertinent lorsque plusieurs personnes ont chacune besoin d’un agent et que vous voulez centraliser les identifiants : un seul magasin à faire tourner, un seul journal d’audit à consulter et un seul tableau de bord où la révocation de l’accès d’une personne révoque effectivement cet accès. C’est un véritable problème opérationnel. Copier une clé d’API sur six ordinateurs portables est une réponse moins sûre.
Pour une seule personne, cela représente beaucoup d’infrastructure sans réel avantage. Vous devriez exécuter PostgreSQL, un control plane, une gateway et un runner pour vous fournir un seul agent. Or le problème des credentials que la gateway résout est presque inexistant lorsque vous êtes la seule personne à détenir la clé. Exécutez plutôt un harness unique sur une machine moins puissante : un harness d’agent unique sur un VPS remplit ce rôle avec une fraction de la mémoire. Si vous n’avez encore choisi aucune orientation, l’étude comparatif des agents IA auto-hébergés constitue une première étape moins coûteuse. Si ce sont les agents eux-mêmes qui vous sont peu familiers, plutôt que les serveurs qui les exécutent, commencez par un parcours progressif pour comprendre le fonctionnement réel des agents. Comprendre le fonctionnement réel d’un appel d’outil et d’un stockage mémoire vous permet de déterminer les autorisations à accorder à l’agent de chaque personne.
FAQ
Quelles sont les exigences minimales du serveur pour auto-héberger OneCLI ?
Docker avec le plugin Compose en version 2.24.0 ou ultérieure, Node.js et pnpm pour l’assistant de configuration utilisé ici, ainsi que suffisamment de mémoire. PostgreSQL est fourni avec le fichier Compose ; vous n’avez donc pas besoin de l’installer séparément. La mémoire détermine le dimensionnement : le runner limite par défaut chaque sandbox d’agent à 2048 MB, et sa documentation recommande environ 10 GiB libres en plus de la stack de base pour servir la limite par défaut de quatre sandboxes. Selon l’hypothèse du graphique, qui prévoit 2 GB pour la stack de base, une machine de 4 GB permet de prévoir une sandbox à sa limite maximale, tandis qu’une machine de 16 GB couvre la limite de concurrence par défaut. Il s’agit de chiffres de planification, pas d’exigences minimales mesurées ni d’allocations mémoire fixes.
OneCLI a-t-il besoin de PostgreSQL, ou peut-il utiliser SQLite ?
Il a besoin de PostgreSQL. DATABASE_URL est documenté comme une chaîne de connexion PostgreSQL, le fichier Compose fourni exécute postgres:18-alpine avec un volume pgdata, et un service de migrations distinct applique le schéma avant le démarrage de l’API. Aucune option SQLite n’est documentée. Si vous utilisez un serveur PostgreSQL externe, configurez l’API et le service de migrations pour l’utiliser ; le fichier Compose fourni définit leurs chaînes de connexion vers son service PostgreSQL inclus.
La sandbox de l’agent OneCLI constitue-t-elle une véritable frontière de sécurité ?
Le mécanisme Compose documenté utilise un conteneur Docker avec des limites de mémoire, de CPU et de processus. Le conteneur est connecté à un réseau marqué internal: true, afin que le trafic externe passe par la gateway. Le contrôle des connexions sortantes est réel et vous pouvez le vérifier avec docker network inspect. L’agent s’exécute sous node, avec no-new-privileges, toutes les capabilities Linux supprimées et le profil seccomp par défaut de Docker, tout en partageant le kernel de l’hôte. Le runner et le terminateur SSH montent tous deux /var/run/docker.sock, ce qui équivaut à un accès root sur un hôte utilisant un daemon Docker rootful. Exécutez OneCLI sur une machine dédiée et conservez les sauvegardes sur une autre machine.
Dois-je ouvrir des ports entrants pour OneCLI ?
Non. Le runner fonctionne uniquement en sortie et n’expose aucun port accessible depuis l’extérieur. Il fonctionne donc derrière un NAT, sans tunnel. Par défaut, le fichier Compose lie le dashboard, la gateway, l’API, PostgreSQL et, avec le profil runner, la porte d’entrée SSH sur 10257 à 127.0.0.1. Accédez au dashboard via un tunnel SSH. Vous pouvez aussi utiliser la configuration de reverse proxy fournie par le projet, avec TLS et les routes nécessaires vers le dashboard, l’API et la gateway, si plusieurs personnes doivent y accéder. Gardez à l’esprit que l’inscription reste ouverte à toute personne pouvant y accéder. La gateway sur 10255 est destinée aux agents. Sur une machine unique, ces agents y accèdent via le réseau Docker interne.
OneCLI est-il gratuit pour une utilisation en entreprise ?
Le cœur du projet est sous licence Apache-2.0 et son utilisation en production sur une infrastructure auto-hébergée est autorisée sans licence commerciale. Les répertoires nommés ee/ sont couverts par la OneCLI Enterprise License. Celle-ci est gratuite pour le développement, les tests et l’évaluation, mais nécessite un abonnement en production. La séparation évolue entre les releases. Les notes de la v2.0.1 du 18 August 2026 mentionnent le rétablissement d’un fichier de licence Apache-2.0 détectable par GitHub. Vérifiez donc LICENSE et les répertoires ee/ dans le tag exact que vous déployez avant de baser un workflow sur une fonctionnalité particulière.