Factory Droid + JoinGonka Gateway : BYOK sur les modèles du réseau Gonka

Étape 1 : installer Droid. Les méthodes officielles de la documentation Factory :

# macOS and Linux
curl -fsSL https://app.factory.ai/cli | sh

# Homebrew
brew install --cask droid

# Windows (PowerShell)
irm https://app.factory.ai/cli/windows | iex

# via npm
npm install -g droid

Le script place le binaire dans ~/.local/bin et indique comment ajouter le répertoire à PATH ; sur Linux, la documentation demande d'installer en plus le paquet xdg-utils. Vérification — droid --version.

Étape 2 : obtenir une clé. Inscrivez-vous sur gate.joingonka.ai/register, confirmez votre adresse et créez une clé avec le préfixe jg- dans la section « Clés API ». Une seule clé et un seul solde fonctionnent pour tous les modèles du réseau.

Étape 3 : lancer l'installeur.

npx @joingonka/setup --tool droid

L'installeur demandera la clé — elle n'est pas transmise dans les arguments de la ligne de commande, pour ne pas rester dans l'historique du shell — et fera quatre choses :

• ajouter au tableau customModels du fichier ~/.factory/settings.json (sur Windows — %USERPROFILE%\.factory\settings.json) une entrée par modèle du réseau : adresse de la passerelle, type de fournisseur generic-chat-completion-api, clé en clair, véritable fenêtre de contexte et plafond de réponse ; le fichier recevra les droits 600 ;
• définir le modèle par défaut — sessionDefaultSettings.model — sur DeepSeek V4 Flash, mais uniquement s'il n'est pas choisi ou s'il pointe vers un modèle qui a quitté le réseau. Il n'intercepte pas un modèle du catalogue Factory ni une entrée BYOK tierce, mais indique comment basculer ;
• conserver une copie de l'ancien fichier, et laisser intactes les entrées tierces dans customModels, les autres réglages et les commentaires ; un fichier impossible à analyser ne sera pas écrasé, mais il indiquera quoi corriger ;
• enfin, envoyer une requête en direct à la passerelle et dire clairement si la clé, l'adresse et le modèle sont acceptés.

Un autre modèle par défaut se définit avec le flag --model et l'abréviation deepseek, glm ou minimax — un modèle explicitement indiqué est toujours enregistré. Pour les dotfiles et les serveurs, il existe un mode sans questions, où la clé est prise dans une variable d'environnement :

JOINGONKA_API_KEY=jg-your-key npx @joingonka/setup --tool droid --model glm --non-interactive

Pas besoin de redémarrer Droid : il remarque lui-même les changements dans settings.json. La ligne ! Could not verify right now avec une réponse 429 à la fin signifie un modèle occupé, et non une erreur de configuration — la configuration est déjà enregistrée.

Tout ce que fait l'installateur peut être fait à la main. Les paramètres utilisateur de Droid sont stockés dans ~/.factory/settings.json ; si le fichier n'existe pas, Droid le crée au premier lancement. Pour le réseau Gonka, il faut le tableau customModels et un modèle par défaut :

{
  "customModels": [
    {
      "model": "deepseek-ai/DeepSeek-V4-Flash-0731",
      "id": "custom:deepseek-ai/DeepSeek-V4-Flash-0731",
      "displayName": "DeepSeek V4 Flash (Gonka)",
      "baseUrl": "https://gate.joingonka.ai/v1",
      "apiKey": "jg-your-key",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 32768,
      "maxContextLimit": 380000,
      "noImageSupport": true
    },
    {
      "model": "zai-org/GLM-5.3-Flash",
      "id": "custom:zai-org/GLM-5.3-Flash",
      "displayName": "GLM 5.3 Flash (Gonka)",
      "baseUrl": "https://gate.joingonka.ai/v1",
      "apiKey": "jg-your-key",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 8192,
      "maxContextLimit": 390000,
      "noImageSupport": true
    },
    {
      "model": "MiniMaxAI/MiniMax-M2.7",
      "id": "custom:MiniMaxAI/MiniMax-M2.7",
      "displayName": "MiniMax M2.7 (Gonka)",
      "baseUrl": "https://gate.joingonka.ai/v1",
      "apiKey": "jg-your-key",
      "provider": "generic-chat-completion-api",
      "maxOutputTokens": 8192,
      "maxContextLimit": 200000,
      "noImageSupport": true
    }
  ],
  "sessionDefaultSettings": {
    "model": "custom:deepseek-ai/DeepSeek-V4-Flash-0731"
  }
}

Le modèle par défaut est stocké dans sessionDefaultSettings.model et pointe vers une entrée via son id. La documentation de Factory mentionne aussi une clé model à la racine du fichier, mais dans notre essai, droid exec sans le flag -m prenait bien le modèle depuis sessionDefaultSettings — y compris après modification de la valeur.

La clé est stockée en clair dans le fichier : protégez-le avec chmod 600 ~/.factory/settings.json et ne recopiez pas les entrées contenant la clé dans le .factory/settings.json du projet — ce fichier finit généralement dans le dépôt. Et si le fichier a une autre allure après le lancement de Droid, c'est normal : à chaque sauvegarde d'un paramètre, Droid réécrit tout le fichier — il réordonne les clés, ajoute un champ index aux entrées et ne conserve pas les commentaires. Les droits 600 restent en place, et l'installateur met à jour ces entrées sans problème.

Droid affiche ses propres entrées séparément du catalogue : d'après la documentation, en mode interactif, la commande /model les liste dans la section Custom models, et Ctrl+N permet de parcourir les modèles directement dans le champ de saisie. En mode ponctuel, le modèle est défini par le flag -m avec la valeur du champ id, les slashes s'écrivent tels quels : droid exec -m custom:zai-org/GLM-5.3-Flash "…".

Si vous vous trompez de nom, Droid répondra Invalid model et listera tous les modèles qu'il détecte, y compris les vôtres sous la forme custom:… (display name) : vous verrez ainsi que vos entrées ont bien été chargées. Un nom au format de la documentation Factory, composé du libellé et du numéro (custom:DeepSeek-V4-Flash-(Gonka)-0), ne fonctionnera pas avec un id explicite — dans notre test, il a donné le même Invalid model.

Ce qui exige un compte Factory. Les modèles personnalisés éliminent la question du paiement des tokens, mais pas celle de la connexion au produit lui-même. Voici ce qu'a montré notre test de Droid 0.225.1 sans connexion au compte :

Pour travailler dans l'interface, créez un compte Factory et connectez-vous via le navigateur — option Login ou commande /login ; sur une machine sans navigateur, la documentation propose une clé issue des paramètres du compte dans la variable FACTORY_API_KEY. Le fonctionnement de droid exec sans connexion est pratique pour tester, mais n'est pas officiellement documenté — ne comptez pas dessus en CI. Selon la page tarifaire de Factory, le BYOK est inclus dans tous les forfaits individuels avec une limite gratuite, et au-delà de cette limite, l'utilisation du BYOK est facturée selon les conditions du forfait ; les conditions actuelles sont sur factory.ai/pricing. Les tokens des modèles du réseau sont quant à eux payés séparément — depuis le solde JoinGonka.

Quel modèle choisir. Le prix est identique pour tous les modèles du réseau, le choix se fait donc sur le comportement. Voici comment ils se sont comportés dans notre test droid exec sur une même tâche — lire un fichier et trouver l'erreur :

Le flag -r (niveau de raisonnement) ne s'applique pas aux modèles BYOK, d'après la documentation Factory. Pourquoi DeepSeek V4 Flash est choisie par défaut, c'est détaillé dans l'aperçu du modèle.

Placez dans un répertoire vide un fichier calc.py contenant une erreur évidente — par exemple, l'aire d'un rectangle où les côtés sont additionnés au lieu d'être multipliés — et demandez à Droid de la trouver :

droid exec "Read the file calc.py in the current project directory and tell me in one sentence whether it has a bug."

Sans options, droid exec fonctionne en lecture seule : on peut consulter les fichiers, pas les modifier. L'agent appellera lui-même l'outil de lecture et répondra concrètement, en indiquant l'expression fautive. Avec l'option -o json, la réponse arrive sous forme d'un seul objet, pratique à traiter par script (sortie abrégée) :

{"type":"result","subtype":"success","is_error":false,"duration_ms":2239,"num_turns":2,
 "result":"Yes, the file has a bug: the rectangle area is computed as the sum of the side lengths, but it should be their product (width * height). …",
 "usage":{"input_tokens":19016,"output_tokens":146,"factory_credits":0,"ttft_ms":747}}

Le champ factory_credits: 0 confirme que le travail s'est fait sur votre modèle, et non sur les crédits Factory. Pour que l'agent puisse modifier les fichiers, ajoutez un niveau d'autonomie : droid exec --auto low "Fix the bug in calc.py and change nothing else." — lors de notre test, DeepSeek V4 Flash a lu le fichier, remplacé l'addition par une multiplication et lancé le script elle-même pour vérifier que 12 s'affiche.

Troisième vérification, côté passerelle : dans la console, à la rubrique « Utilisation », la requête apparaîtra dans la répartition « Par modèles », et dans le bloc « Par clés », l'heure de la dernière requête sera mise à jour.

Si quelque chose ne fonctionne pas, gardez à l'esprit cette particularité de Droid : dans la console, droid exec n'affiche que Error during droid execution: Exec failed (en JSON — "result":"Exec failed"), tandis que la vraie cause reste dans le journal. On peut la récupérer en une seule commande :

grep agent_error_count ~/.factory/logs/droid-log-single.log | grep -o '"errorMessage":"[^,]*' | tail -1

L'outil d'agent consomme des jetons différemment d'un chat : pour chaque phrase, Droid ajoute un prompt système, les descriptions des outils et un instantané du répertoire de travail, et une tâche prend plusieurs tours. Dans notre test, chaque tour consommait environ 9,5 milliers de jetons en entrée avant même votre question : la tâche « lire le fichier et trouver l'erreur » a pris deux tours et environ 19 milliers de jetons, « corriger et vérifier » — quatre tours et environ 44 milliers. C'est pourquoi le prix par jeton est ici déterminant.

Via le JoinGonka Gateway, les jetons coûtent $0.0069 par million en entrée et $0.021 par million en sortie — le prix est identique pour tous les modèles du réseau et est mis à jour sur cette page à partir d'une source en temps réel.

Les estimations dans la colonne de droite sont basées sur les prix de septembre 2026. À titre de comparaison — comment payer les modèles dans Droid :

La commande /cost dans l'interface Droid affiche les statistiques de la session, tandis que la consommation précise et le solde pour les modèles BYOK se trouvent dans le tableau de bord de la passerelle, dans les sections « Utilisation » et « Facturation ». Créez une clé distincte pour Droid — son trafic sera visible sur une ligne séparée.

Autonomie. En mode ponctuel, Droid ne fait que lire par défaut ; les droits s'étendent par niveaux : --auto low — modifications de fichiers, --auto medium — en plus l'installation de dépendances, la compilation, les tests et les commits locaux, --auto high — jusqu'au push et au déploiement. L'option --skip-permissions-unsafe lève toutes les vérifications — uniquement pour des conteneurs jetables. En mode interactif, le niveau se change avec Ctrl+L, et le niveau de départ est défini par sessionDefaultSettings.autonomyLevel ; par défaut, c'est off — tout avec confirmation.

Signature dans les commits. Le réglage includeCoAuthoredByDroid est activé par défaut : Droid ajoute une ligne de co-auteur dans les messages de commit. Si vous n'en voulez pas, écrivez "includeCoAuthoredByDroid": false dans settings.json.

Où sont stockées les sessions. Après connexion au compte, Droid réplique par défaut les sessions du CLI vers la version web de Factory — c'est le rôle de cloudSessionSync. Les clés BYOK, selon la documentation, restent locales ; si vous voulez aussi que les échanges restent sur la machine, mettez "cloudSessionSync": false. De son côté, la passerelle ne conserve pas le contenu des prompts et des réponses — seuls des agrégats de consommation restent dans les statistiques.

Mises à jour. L'installation par script se met à jour toute seule ; on peut figer la version avec la variable FACTORY_DROID_AUTO_UPDATE_ENABLED=false ou la commande droid update --version <version> ; les builds depuis npm ne se mettent pas à jour d'eux-mêmes. Après une mise à jour, vérifiez en un droid exec que les modèles du réseau sont bien là.

Images. Les modèles du réseau sont textuels ; pour les captures d'écran, gardez à côté une entrée avec un modèle capable de vision, chez un autre fournisseur.

Si travailler sans compte fournisseur est indispensable. Les mêmes modèles du réseau se connectent à des agents terminaux ouverts, qui n'exigent pas de connexion — par exemple à OpenCode avec le même installateur, via l'option --tool opencode.