Configurer dsh : clé API, modèles et endpoints

Emplacement de la configuration de dsh

dsh (DeepSeek Harness) conserve sa configuration dans un seul répertoire : $DSH_HOME, qui correspond par défaut à ~/.dsh. Tout ce que vous définissez dans l’interface Web y est enregistré sous forme de fichiers texte. Copiez ce répertoire sur un autre serveur pour que le nouveau système se comporte comme l’ancien.

Quatre chemins contiennent tout ce que vous aurez à modifier.

• ~/.dsh/settings.yaml contient les paramètres écrits manuellement ou depuis l’interface, notamment vos routes de fournisseur et de modèle.
• ~/.dsh/.credentials.yaml contient les secrets. Les paramètres ne conservent qu’une référence à un identifiant, et la valeur de la clé se trouve dans un seul fichier.
• ~/.dsh/profiles/ contient les profils nommés, et ~/.dsh/storages/ contient les sessions enregistrées.
• ~/.dsh/cordis.patch.yml constitue votre couche de correctifs. Elle est appliquée par-dessus la configuration intégrée pour chaque profil.

DeepSeek a présenté le harness comme une préversion pour développeurs sous licence MIT le 17 August 2026, et le README indique que des changements incompatibles sont prévus. Les noms de champs et les chemins de ce guide correspondent à la documentation du dépôt en August 2026. Vérifiez-les dans la documentation correspondant à la version que vous avez installée avant de copier la configuration depuis un guide, y compris celui-ci, car une préversion peut renommer des éléments d’une release à l’autre.

Le minimum honnête pour obtenir une première sortie

dsh nécessite Node.js 22.19 ou une version ultérieure de la branche 22, ou la version 24 ou une version ultérieure. Node 23 n’est pas pris en charge. Vérifiez d’abord la version, car une incompatibilité de version provoque un échec au démarrage et le message d’erreur donne l’impression que le package est défectueux.

node -v
npx @deepseek-ai/dsh web

npx télécharge le package depuis le registre npm et démarre l’interface Web sur http://127.0.0.1:3080. Il se lie à l’adresse de loopback. Le port n’est donc pas accessible depuis une autre machine, même si votre pare-feu l’autorise. Sur un VPS, transférez plutôt le port via SSH au lieu d’ouvrir 3080 sur Internet.

ssh -N -L 3080:127.0.0.1:3080 you@your-server

Ouvrez http://127.0.0.1:3080 sur votre ordinateur portable, puis accédez à Settings et Models. La fiche DeepSeek contient un seul champ pour la clé API. Collez la clé obtenue sur platform.deepseek.com, puis enregistrez-la. La route du modèle devient immédiatement utilisable, sans redémarrage, car le serveur en cours d’exécution stocke l’identifiant et résout la référence à la volée. Accéder à l’interface Web de dsh sur un serveur distant présente le tunnel et le cas du reverse proxy, tandis que installer DeepSeek Harness sur un VPS couvre la préparation du serveur supposée par ce guide.

Après l’enregistrement, vérifiez ce que l’application a créé.

ls -la ~/.dsh
stat -c '%a %n' ~/.dsh/.credentials.yaml

Vous devriez voir settings.yaml, .credentials.yaml et profiles/. Si stat affiche un mode différent de 600, exécutez chmod 600 ~/.dsh/.credentials.yaml. Un fichier d’identifiants lisible par le groupe ou par tous les utilisateurs expose votre clé à tous les autres comptes du serveur.

Pour une première exécution sans navigateur, une seule commande suffit.

npx @deepseek-ai/dsh --profile headless "summarise the files in this directory"

Le profil headless exécute une session unique et affiche la réponse finale.

Variables d’environnement ou fichier de configuration

Il existe deux façons de fournir une clé à dsh. Elles ne sont pas interchangeables.

Un fournisseur du catalogue (DeepSeek, Anthropic, OpenAI et les autres fournisseurs intégrés) reçoit sa clé depuis la page Models. La valeur est enregistrée dans ~/.dsh/.credentials.yaml, et vos paramètres ne contiennent qu’une référence vers celle-ci. L’interface Web n’affiche plus la clé après son enregistrement.

Un fournisseur personnalisé peut utiliser à la place une variable d’environnement, avec apiKeyEnv. C’est la structure indiquée par la documentation pour ~/.dsh/settings.yaml.

llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.example/v1
      models:
        - id: legacy-chat
        - id: vision-preview
          input: [text, image]

Ajoutez d’abord un fournisseur depuis l’interface Web, puis ouvrez ~/.dsh/settings.yaml et copiez la structure qui y a été écrite. Pendant une developer preview, c’est l’imbrication qui risque le plus de changer, et le fichier que l’application vient d’écrire est toujours à jour.

apiKeyEnv est lu dans l’environnement du processus dsh, et non dans celui de votre login shell. Une clé exportée dans une session interactive est invisible pour une unité systemd. Ainsi, la même configuration qui fonctionne lorsque vous saisissez dsh web manuellement renvoie MISSING_CREDENTIAL avec un service. Donnez à l’unité son propre fichier.

[Service]
EnvironmentFile=/etc/dsh/dsh.env

Conservez ce fichier avec le mode 600 et attribuez-le à l’utilisateur sous lequel le service s’exécute.

Choisir les modèles et l’identifiant impossible à renommer

Tous les fournisseurs configurés apparaissent dans le sélecteur de modèles. La sélection d’un modèle en fait également le modèle par défaut des nouvelles sessions. Les sessions déjà créées conservent le modèle qui y est enregistré. Le changement ne réécrit donc pas une ancienne conversation.

L’identifiant du fournisseur est permanent. Les requêtes, les sessions enregistrées, les modèles par défaut et les références aux identifiants d’authentification l’utilisent. Il n’existe donc aucun bouton pour le renommer. Pour le modifier, vous devez créer un nouveau fournisseur et supprimer l’ancien. Choisissez un nom que vous pourrez conserver : local-ollama plutôt que test2.

Les modèles sont uniquement textuels, sauf indication contraire. Ajoutez input: [text, image] à une entrée de modèle pour déclarer la prise en charge des images, ou définissez defaultInput au niveau de la route comme valeur de repli pour les modèles que le catalogue ne décrit pas. La route chat-completions de DeepSeek est uniquement textuelle et ne peut pas être configurée autrement. Une image jointe à cette route est donc refusée avant tout envoi.

Pointez dsh vers un endpoint local pour que votre code reste sur le serveur

Ollama fournit une API compatible avec OpenAI sur http://127.0.0.1:11434/v1. dsh peut utiliser n’importe quelle base URL compatible avec OpenAI via un fournisseur personnalisé. Les deux services communiquent donc directement. Configurez d’abord le serveur de modèles : auto-héberger un LLM avec Ollama sur un VPS explique l’installation et le téléchargement du modèle.

Vérifiez que l’endpoint répond avant de modifier dsh.

ollama list
curl -s http://127.0.0.1:11434/v1/models

ollama list affiche le tag exact de chaque modèle téléchargé. Copiez cette chaîne. curl renvoie les mêmes modèles au format JSON. Une liste vide signifie qu’Ollama fonctionne sans modèle téléchargé. Connection refused signifie qu’Ollama ne fonctionne pas ou n’écoute pas sur 11434.

Ajoutez maintenant le fournisseur. Ollama exige un champ de clé API, mais ignore sa valeur. N’importe quelle chaîne non vide convient donc.

llm-pi-ai:
  providers:
    local-ollama:
      apiKeyEnv: OLLAMA_API_KEY
      api: openai-completions
      baseURL: http://127.0.0.1:11434/v1
      models:
        - id: <the exact tag printed by ollama list>

Exportez la variable dans l’environnement auquel le processus dsh aura accès.

sudo install -d -m 700 /etc/dsh
printf 'OLLAMA_API_KEY=ollama\n' | sudo tee /etc/dsh/dsh.env
sudo chmod 600 /etc/dsh/dsh.env

Trois erreurs couvrent presque toutes les tentatives. MISSING_CREDENTIAL signifie que dsh n’a pas pu lire la variable indiquée par apiKeyEnv. Vérifiez donc l’environnement du processus, et non celui de votre terminal. UNKNOWN_MODEL signifie que le id ne correspond à aucun modèle configuré. Comparez-le caractère par caractère avec ollama list, y compris le tag situé après les deux-points. Une erreur 401 lors de la récupération des modèles disponibles provient de la découverte des modèles, qui appelle GET /models sur votre base URL. Les endpoints qui ne fournissent pas ce chemin nécessitent de saisir les modèles manuellement.

La base URL constitue un autre piège. Laissez /v1 en dehors de celle-ci : les requêtes aboutiront alors sur des chemins qu’Ollama ne fournit pas. L’appel renverra une erreur 404 et le modèle ne s’exécutera jamais. Ce suffixe fait partie de l’interface compatible avec OpenAI ; ce n’est pas un élément décoratif.

Si Ollama s’exécute sur une autre machine, l’adresse de cette machine devient la base URL. Vos prompts traversent alors le réseau en clair via HTTP. Conservez Ollama sur le même hôte ou placez-le derrière TLS (transport layer security) et une authentification : sécuriser un endpoint Ollama exposé.

Ce qui quitte la machine dans chaque mode

Avec une clé DeepSeek, chaque requête est envoyée à l’API de DeepSeek. Elle contient votre prompt, le contenu des fichiers que l’agent a lus pour y répondre, la sortie des commandes qu’il a exécutées et les résultats des outils qu’il a choisi d’inclure. Votre code source se trouve dans cette charge utile dès que l’agent a ouvert un fichier. C’est le fonctionnement d’un modèle hébergé. Vous devez donc choisir avec attention le répertoire depuis lequel vous démarrez l’agent.

Avec un autre fournisseur du catalogue ou une passerelle d’entreprise, la même charge utile est envoyée à ce fournisseur. L’URL de base vous indique exactement sa destination.

Avec un endpoint local, la requête destinée au modèle est envoyée à 127.0.0.1:11434 et reste sur la machine. Aucun élément de votre code ne parvient à un fournisseur de modèles. Trois éléments traversent tout de même le réseau. npx télécharge le package depuis le registre npm. Tous les outils exécutés par l’agent peuvent accéder eux-mêmes à Internet, notamment les serveurs MCP (model context protocol) que vous avez connectés, comme l’explique en détail exécuter des serveurs MCP sur un VPS. La télémétrie peut également le faire si vous l’activez.

La télémétrie est désactivée tant que vous ne l’avez pas activée explicitement. DSH_TELEMETRY_MODE est le sélecteur de consentement. Les valeurs non définies, vides ou non reconnues sont interprétées comme DISABLED. Dans cet état, dsh ne construit aucun provider, processor ou exporter OpenTelemetry (OTel). Un profil vierge n’effectue donc aucune requête réseau de télémétrie. FEEDBACK_ONLY active le partage des journaux de session déclenché par un retour utilisateur. FULL autorise également les rapports du launcher. Le flux de session peut exporter le contenu de la session, les données des outils, les prompts et les chemins de l’espace de travail. Considérez donc FULL comme l’envoi de votre travail à DeepSeek.

Pour bloquer complètement ce comportement sans dépendre d’une valeur correcte du mode, définissez DSH_TELEMETRY_DISABLED=1. Toute valeur non vide constitue un refus explicite. Elle est lue avant le démarrage de l’exécution. Le code du projet ne peut donc pas réactiver la télémétrie au milieu de la session. L’adresse par défaut du collector est harness-telemetry.deepseeksvc.com. Il est utile de connaître ce nom lorsque vous consultez vos propres journaux de firewall.

Vérifiez ce comportement au lieu de faire confiance à la configuration. Pendant l’exécution d’une tâche, listez les connexions sortantes détenues par le processus.

sudo ss -tnp | grep -i node

En mode modèle local, vous devez voir la connexion loopback vers 11434 et aucune connexion vers une adresse publique. Tout autre élément doit être identifié avant de continuer. Ce qu’un agent de programmation envoie à l’extérieur effectue la même vérification avec d’autres harnesses et explique comment interpréter le résultat.

Les emplacements à éviter pour les secrets

• Historique du shell. export DEEPSEEK_API_KEY=sk-... est écrit en clair dans ~/.bash_history et y reste longtemps après la rotation de la clé. Préfixez la commande par une espace lorsque HISTCONTROL=ignorespace est défini, ou évitez le shell et écrivez directement la valeur dans un fichier avec le mode 600.
• Fichiers dot versionnés. Une clé dans ~/.bashrc ou ~/.zshrc n’est qu’à git add d’un dépôt public si vous versionnez vos fichiers dot avec git. Exécutez git grep -I -n 'sk-' dans ce dépôt avant le push.
• settings.yaml. Utilisez apiKeyEnv pour les providers personnalisés afin que le fichier contienne un nom de variable plutôt qu’un secret. Les fichiers de configuration sont souvent copiés dans des rapports d’incident et des conversations avec le support. Ce n’est pas le cas des fichiers d’identifiants.
• Sortie de env et captures d’écran du terminal. Toute commande qui affiche l’environnement complet affiche aussi la clé.
• Sauvegardes. ~/.dsh doit être sauvegardé, mais .credentials.yaml qu’il contient est un secret actif. Excluez ce fichier ou chiffrez l’archive.

Ces règles ne concernent pas uniquement dsh. Garder les secrets hors des fichiers env de Compose traite le même problème côté conteneurs sur le même serveur.

Utiliser une version en préversion développeur

Figez la version que vous avez testée, car une préversion peut modifier une clé de configuration dans une mise à jour corrective, ce qui empêche ensuite votre provider de se charger. Conservez settings.yaml et cordis.patch.yml dans le contrôle de version, en excluant le fichier d’identifiants, afin de voir ce qui a changé après une mise à niveau.

Deux options sont utiles lorsqu’un profil ne se comporte pas comme prévu. --dump-default-config affiche la configuration par défaut assemblée sans démarrer le service, et --dump-config affiche de la même manière la configuration assemblée pour votre profil. La comparaison des deux montre précisément les modifications apportées par votre couche de surcharge. C’est plus rapide que d’examiner les différentes couches manuellement.

dsh --profile web --dump-config

Lorsqu’un problème survient après une mise à niveau, exécutez d’abord cette commande. Une clé déplacée entre deux versions apparaît comme une branche manquante dans le dump. La correction se résume alors à modifier une seule ligne, sans réinstaller le logiciel.

FAQ

Où dsh stocke-t-il ma clé API DeepSeek ?

Dans $DSH_HOME/.credentials.yaml, qui est ~/.dsh/.credentials.yaml sauf si vous définissez vous-même DSH_HOME. La page Models y écrit la clé, et vos paramètres ne contiennent qu’une référence vers celle-ci. Le secret se trouve donc dans un seul fichier. Vérifiez le mode avec stat -c '%a %n' ~/.dsh/.credentials.yaml et définissez-le à 600 s’il est moins restrictif. Un fournisseur personnalisé peut éviter complètement ce fichier en indiquant une variable d’environnement avec apiKeyEnv.

Comment faire utiliser à dsh un modèle local au lieu de l’API DeepSeek ?

Ajoutez un fournisseur personnalisé dont l’URL de base pointe vers votre endpoint local compatible avec OpenAI. Pour Ollama, il s’agit de http://127.0.0.1:11434/v1, avec api: openai-completions et un modèle id copié exactement depuis ollama list. Ollama exige une valeur de clé API, mais l’ignore. Toute chaîne non vide convient donc. Vérifiez que l’endpoint répond avec curl -s http://127.0.0.1:11434/v1/models avant de modifier la configuration de dsh, car un endpoint indisponible et une configuration incorrecte produisent des erreurs similaires.

dsh envoie-t-il mon code quelque part par défaut ?

Avec un modèle hébergé, oui. Votre prompt et le contenu des fichiers lus par l’agent se trouvent dans la requête API envoyée à ce fournisseur. Avec un endpoint local, cette requête est envoyée à loopback et reste sur la machine. La télémétrie est un flux distinct et elle est désactivée par défaut : DSH_TELEMETRY_MODE renvoie DISABLED lorsqu’elle n’est pas définie, et aucun exporteur n’est créé dans cet état. Définissez DSH_TELEMETRY_DISABLED=1 pour désactiver la télémétrie avant le démarrage de l’exécution.

Pourquoi dsh signale-t-il MISSING_CREDENTIAL alors que ma variable est définie ?

Parce que dsh lit, dans l’environnement de son propre processus, la variable indiquée par apiKeyEnv. Une variable exportée dans votre shell n’est pas transmise à un service systemd, à la session d’un autre utilisateur ou à un processus démarré avant son exportation. Placez la valeur dans un EnvironmentFile avec le mode 600 pour l’unité, ou exportez-la dans le même shell que celui qui démarre dsh. Vérifiez ce que contient réellement le processus en cours avec sudo tr '\0' '\n' < /proc/$(pgrep -f dsh | head -1)/environ.

Quelle version de Node.js dsh nécessite-t-il ?

Node.js 22.19 ou une version ultérieure de la ligne 22, ou Node.js 24 ou une version ultérieure. Node.js 23 ne fait pas partie des versions prises en charge. Exécutez node -v avant toute autre opération, car un échec au démarrage dû à un runtime non pris en charge ressemble à une installation défectueuse. Cela conduit souvent à réinstaller le package au lieu du runtime.