SSD Nodes Learn Hosting plans →
Guides Matt ConnorPar Matt Connor · Mis à jour le 2026-11-06

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

Découvrez où dsh stocke sa configuration Linux, comment utiliser une clé DeepSeek ou Ollama en local, et quelles données sortent exactement selon le mode choisi.

Emplacement de la configuration de dsh

dsh (DeepSeek Harness) stocke les données de son harness dans $DSH_HOME, qui est par défaut ~/.dsh, et lit la configuration partagée des agents depuis une racine distincte, $DSH_AGENTS_HOME, qui est par défaut ~/.agents. Tout ce que vous définissez dans l’interface Web y est écrit sous forme de fichiers texte. Lorsque vous déplacez votre configuration vers un autre serveur, copiez le répertoire home du harness ainsi que les instructions et skills globales depuis la racine partagée des agents.

Quatre chemins contiennent les principaux paramètres du harness, les secrets et les journaux de session.

  • ~/.dsh/profiles/<profile>/cordis.patch.yml contient les paramètres écrits par l’interface Web pour ce profil, notamment vos routes vers les providers et les modèles. dsh web exécute le profil web, le fichier est donc ~/.dsh/profiles/web/cordis.patch.yml.
  • ~/.dsh/.credentials.yaml contient les secrets. Les paramètres ne conservent qu’une référence à un identifiant, et sa valeur est stockée dans un seul fichier.
  • ~/.dsh/profiles/ contient les profils nommés, et ~/.dsh/sessions/ contient les journaux de session enregistrés.
  • ~/.dsh/cordis.patch.yml constitue votre propre couche de correctifs. Elle est appliquée par-dessus la configuration intégrée pour chaque profil et prend le pas sur le fichier du profil. Une modification de l’interface Web que cette couche remplacerait est donc refusée au lieu d’être enregistrée.

La racine partagée des agents reste en dehors de $DSH_HOME, car d’autres outils d’agents l’utilisent également. dsh lit les instructions globales de l’utilisateur dans ~/.agents/AGENTS.md et recherche les skills dans ~/.agents/skills/. Définissez DSH_AGENTS_HOME pour déplacer cette racine.

Les anciennes builds stockaient ces paramètres dans ~/.dsh/settings.yaml. Les builds actuelles importent une seule fois ce fichier dans le profil actif et le renomment en settings.yaml.imported. Un ancien guide qui vous indique de modifier settings.yaml fait donc désormais référence à un fichier que dsh ne lit plus.

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

Le minimum réaliste jusqu’à la première sortie

dsh nécessite Node.js 24.9 ou une version ultérieure. Au 5 novembre 2026, son package.json déclare >=24.9.0 ; la branche 22 n’est donc pas prise en charge. Node 24.0 à 24.8 ne suffit pas non plus. Vérifiez d’abord la version, car une incompatibilité de version fait échouer le démarrage et le message d’erreur donne l’impression que le package est endommagé.

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 loopback. Le port n’est donc pas accessible depuis une autre machine, même si votre pare-feu l’autorise. Sur un VPS, faites-le transiter par SSH au lieu d’ouvrir 3080 sur Internet. Si l’URL affichée vous semble déroutante, pourquoi dsh démarre sur cette adresse explique ce que protège la liaison loopback et ce qu’elle ne protège pas.

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 carte DeepSeek comporte un champ pour la clé API. Collez-y 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 couvre 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 .credentials.yaml et profiles/, avec les paramètres de l’interface Web dans profiles/web/cordis.patch.yml. Un répertoire personnel créé par une version plus ancienne peut également contenir settings.yaml.imported. Si stat affiche un mode différent de 600, exécutez chmod 600 ~/.dsh/.credentials.yaml. Un fichier d’identifiants lisible par le groupe expose votre clé aux comptes de ce groupe ; un fichier lisible par tous l’expose à tous les autres comptes du serveur.

Pour un premier lancement 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

dsh peut résoudre une clé à partir des identifiants enregistrés ou des variables d’environnement de secours.

Un fournisseur de catalogue (DeepSeek, Anthropic, OpenAI et les autres fournisseurs intégrés) accepte une clé via la page Models ou utilise la variable d’environnement de secours correspondante lorsqu’aucun identifiant enregistré ne la fournit. La valeur est placé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 nommer une référence d’identifiant avec apiKeyEnv, qui prend également en charge les variables d’environnement de secours. Voici la structure indiquée dans la documentation pour une entrée d’un correctif de profil tel que ~/.dsh/profiles/web/cordis.patch.yml.

- id: llm-pi-ai
  config:
    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 via l’interface Web, puis ouvrez cordis.patch.yml du profil et copiez la structure qui y a été écrite. Pendant une developer preview, l’imbrication est l’élément le plus susceptible de changer, et le fichier que l’application vient d’écrire est toujours à jour.

apiKeyEnv est résolu via le magasin d’identifiants : le fichier enregistré est prioritaire, suivi de l’environnement de lancement, du .env du répertoire depuis lequel la commande est exécutée, puis de $DSH_HOME/.env. Une clé exportée uniquement dans une session interactive est invisible pour une unité systemd. Sans autre source d’identifiants, la même configuration qui fonctionne lorsque vous saisissez dsh web manuellement renvoie MISSING_CREDENTIAL depuis 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

Chaque fournisseur configuré apparaît 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 qui ont déjà envoyé une requête conservent le modèle qui leur est associé. Le changement ne réécrit donc pas les anciennes conversations.

Le Provider ID est permanent. Les requêtes, les sessions enregistrées, les modèles par défaut et les références aux identifiants d’accès pointent tous vers lui. Il n’existe donc aucun bouton de renommage. Le modifier revient à créer un nouveau fournisseur, puis à supprimer l’ancien. Choisissez un nom que vous pourrez conserver : local-ollama plutôt que test2.

Les modèles personnalisés qui n’héritent pas de la capacité de traitement des images sont limités au texte, sauf indication contraire. Ajoutez input: [text, image] à l’entrée du 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 non décrits dans le catalogue. Sur la route DeepSeek elle-même, un modèle sans modalités déclarées est considéré comme limité au texte. Choisissez donc une entrée du catalogue compatible avec les images (deepseek-flash par défaut) avant de joindre une image. Une image envoyée à un modèle qui ne déclare aucune prise en charge des images est refusée avant tout envoi.

Configurez dsh pour utiliser un endpoint local afin que votre code reste sur le serveur

Ollama expose 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 provider personnalisé. Les deux services communiquent donc directement. Configurez d’abord le model server : héberger vous-même 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 configurer 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 n’est pas démarré ou n’écoute pas sur 11434.

Choisissez un modèle qui peut fonctionner sur cette machine. Un serveur Ollama authentifié peut également servir des modèles cloud via la même adresse locale. Un tag cloud tel que gemma4:cloud exécute alors le modèle sur les serveurs d’Ollama. Vos prompts quittent donc le serveur, même si dsh ne communique qu’avec 127.0.0.1.

Ajoutez ensuite le provider au profile patch. Fournissez une valeur non vide pour la clé API dans cette configuration. Le serveur Ollama local l’ignore.

- id: llm-pi-ai
  config:
    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 de configuration. MISSING_CREDENTIAL signifie que la référence indiquée par apiKeyEnv ne renvoie aucune valeur. Vérifiez donc les credentials enregistrés et l’environnement de lancement, pas uniquement 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 n’exposent pas ce chemin nécessitent de saisir les modèles manuellement.

La base URL constitue un autre piège. Si vous omettez /v1, les requêtes arrivent sur des chemins qu’Ollama n’expose pas. L’appel renvoie alors une erreur 404 et le modèle ne s’exécute jamais. Ce suffixe fait partie de la surface compatible avec OpenAI. Ce n’est pas un élément décoratif.

Si Ollama fonctionne sur une autre machine, l’adresse de cette machine devient la base URL. Vos prompts traversent alors le réseau en clair via HTTP. Laissez Ollama sur le même serveur 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 et le endpoint par défaut, les requêtes au modèle sont envoyées à l’API DeepSeek. Cette requête 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 ainsi qu’un modèle hébergé fonctionne. C’est pourquoi vous devez réfléchir au répertoire depuis lequel vous démarrez l’agent.

Les versions actuelles joignent également aux requêtes, par défaut et via l’adaptateur DeepSeek natif, un suffixe non accepté du journal d’événements de la session, y compris avec les gateways configurées, dans un champ dsh_session_log distinct. Le modèle ne le voit jamais, mais la destination de la requête le reçoit. Désactivez cette fonction dans Settings, General (« Upload Session Log when using the official model API »), ou définissez enabled: false sur le plugin session-log-deepseek. Les commutateurs de télémétrie ci-dessous ne contrôlent pas cet envoi.

Les profils fournis envoient également les noms et les versions des packages de plugins actifs via l’adaptateur DeepSeek natif, dans un champ dsh_plugin_packages distinct. Définissez enabled: false sur plugin-package-inventory-deepseek pour empêcher cette contribution.

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

Avec un endpoint local, la requête au modèle est envoyée à 127.0.0.1:11434, mais l’adresse loopback ne suffit pas à la garder sur la machine. La documentation d’Ollama indique : « To use cloud models through this server, sign in to Ollama ». Ainsi, lorsqu’un modèle cloud est sélectionné via ce même serveur local, vos prompts et votre code sont envoyés au cloud d’Ollama. La requête au modèle reste sur la machine uniquement lorsque le modèle lui-même s’exécute localement. Même dans ce cas, trois éléments traversent encore le réseau. npx télécharge le package depuis le registre npm. Tout outil exécuté par l’agent peut accéder lui-même à Internet, notamment les serveurs MCP (model context protocol) auxquels vous vous êtes connecté ; la section exécuter des serveurs MCP sur un VPS détaille ce point. Un plugin appartient à la même catégorie, car son installation exécute le code d’un autre auteur avec les permissions de votre agent. Il est donc utile de vérifier ce à quoi un plugin peut accéder avant de l’installer. Il en va de même pour la télémétrie : les versions actuelles autorisent son export vers DeepSeek lorsque vous envoyez un feedback, exactement comme avec un modèle hébergé.

Par défaut, la télémétrie se limite au feedback. DSH_TELEMETRY_MODE sélectionne le mode. Dans la configuration de base actuellement fournie, une valeur absente ou vide devient FEEDBACK_ONLY. Dans ce mode, l’activité courante n’autorise aucune capture de télémétrie. Lorsque vous envoyez un feedback écrit, créez ou modifiez une évaluation, modifiez une note ou retirez un feedback, dsh autorise l’export vers https://dsh-otel-collector.deepseeksvc.com/v1/logs du préfixe du journal de session qui n’a pas encore été transmis à l’exporteur, via cet événement de feedback et avec le contexte hérité. La livraison complète n’est pas garantie : un événement trop volumineux est rejeté sans troncature, et les préfixes volumineux peuvent rester partiellement non envoyés à la sortie du CLI. Les lots autorisés peuvent continuer à être envoyés sans nouvelle interaction ni nouvel appel au modèle. Le README de la télémétrie indique que cela s’applique « for all users and providers ». L’exécution locale du modèle ne la désactive donc pas. DISABLED ne construit aucun transport OpenTelemetry (OTel). FULL n’est plus accepté : toute valeur autre que ces deux valeurs est rejetée avec unsupported mode. Un export de feedback peut contenir du texte de message, des arguments et des résultats d’outils, ainsi que des chemins du workspace. Considérez donc l’envoi de feedback comme une autorisation d’envoyer ce préfixe de session à DeepSeek.

Pour un blocage strict qui ne dépend pas d’une valeur de mode correcte, définissez DSH_TELEMETRY_DISABLED=1. Toute valeur non vide constitue un refus d’autorité, notamment 0 et false. Cette valeur est lue avant le démarrage de l’exécution. Le code du projet ne peut donc pas réactiver la fonction au milieu de la session. L’adresse par défaut du collector est dsh-otel-collector.deepseeksvc.com ; DSH_TELEMETRY_OTLP_URL permet de la remplacer.

Vérifiez la configuration au lieu de lui faire confiance. Lorsqu’une tâche s’exécute, listez les connexions sortantes détenues par le processus.

sudo ss -tnp | grep -i node

Avec un modèle exécuté localement, le trafic du modèle utilise le port loopback 11434. Toutefois, les outils peuvent encore établir des connexions publiques sans qu’aucun feedback soit envoyé. Les profils fournis incluent la recherche et la récupération de contenu web, et le preset de permissions par défaut ne restreint pas l’accès réseau. Identifiez chaque destination publique avant de l’attribuer à la télémétrie. Le seul moment d’établissement de la connexion ne prouve pas qu’il s’agit de l’export du feedback. Cet instantané peut également manquer les connexions de courte durée. Cette vérification ne couvre que le processus dsh : le trafic d’un modèle cloud sort du serveur Ollama. Vérifiez donc aussi que le modèle id n’est pas un tag cloud. Tout autre élément doit être identifié avant de poursuivre. 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.

Où les secrets ne doivent pas être stockés

  • 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 dotfiles versionnés. Une clé dans ~/.bashrc ou ~/.zshrc n’est plus qu’à une étape git add d’un dépôt public si vous versionnez les dotfiles avec git. Exécutez git grep -I -n 'sk-' dans ce dépôt avant le push.
  • Fichiers de configuration du profil. Utilisez apiKeyEnv pour les providers personnalisés afin que cordis.patch.yml contienne un nom de variable plutôt qu’un secret. Les fichiers de configuration sont souvent copiés dans les rapports d’incident et les échanges avec le support. Les fichiers de credentials ne le sont pas.
  • 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, et ne pas stocker les secrets dans les fichiers env de Compose couvre le même problème côté conteneurs sur le même serveur.

Utiliser une version en préversion

Épinglez la version que vous avez testée, car une préversion peut modifier une clé de configuration dans une version corrective, ce qui empêche ensuite votre fournisseur de se charger. Si l’installation avec version épinglée refuse alors de démarrer, ou si npx continue de vous fournir une build que vous n’avez pas demandée, les erreurs d’installation et de version produites par une préversion couvrent le cache npx et la version de npm fournie avec Node. Placez le répertoire personnel cordis.patch.yml et les fichiers de correctifs sous profiles/ sous 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 composée sans démarrer le service, et --dump-config affiche de la même manière la configuration composée pour votre profil. La comparaison des deux montre ce que votre couche de correctifs a réellement modifié. C’est plus rapide que de lire 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 limite alors à modifier une ligne, sans réinstaller.

FAQ

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

Dans $DSH_HOME/.credentials.yaml, qui correspond à ~/.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 reste donc dans un seul fichier. Vérifiez le mode avec stat -c '%a %n' ~/.dsh/.credentials.yaml et définissez-le sur 600 s’il est moins restrictif. Un fournisseur personnalisé peut éviter complètement le fichier en indiquant une variable d’environnement avec apiKeyEnv.

Comment faire utiliser à dsh un modèle local plutôt que 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. Indiquez une valeur d’API key non vide pour cette configuration ; le serveur Ollama local l’ignore. 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 sont inclus dans la requête API envoyée à ce fournisseur. Les requêtes utilisant l’adaptateur DeepSeek natif, y compris celles passant par des gateways configurées, contiennent également par défaut un suffixe de session-log, jusqu’à ce que vous désactiviez cet upload dans Settings, General. Avec un modèle exécuté localement par Ollama, la requête est envoyée à loopback et reste sur la machine. En revanche, un modèle cloud tel que gemma4:cloud la transmet au cloud d’Ollama via la même adresse loopback. La recherche web et le fetch intégrés, les autres outils et les plugins peuvent contacter indépendamment des services publics, sans dépendre du feedback. La télémétrie est un flux distinct : dans les versions actuelles, DSH_TELEMETRY_MODE prend la valeur FEEDBACK_ONLY lorsqu’il n’est pas défini. Le feedback autorise donc l’export du préfixe du session-log par cet événement, y compris le contexte hérité, pour tous les fournisseurs, y compris les modèles locaux. La livraison n’est pas garantie, et les uploads autorisés peuvent continuer après l’interaction de feedback. Définissez-le sur DISABLED pour n’utiliser aucun exporter, ou définissez DSH_TELEMETRY_DISABLED=1 pour un opt-out lu avant le démarrage de l’exécution.

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

Parce que la référence indiquée par apiKeyEnv doit être résolue dans les sources d’identifiants de dsh. Les identifiants enregistrés sont prioritaires sur l’environnement de lancement, puis viennent .env et $DSH_HOME/.env du répertoire depuis lequel le processus est lancé. Une variable exportée dans votre shell n’est pas transmise à un service systemd, à la session d’un autre utilisateur ni à 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 24.9 ou une version ultérieure, selon le fichier package.json du dépôt au 5 novembre 2026. La branche 22 n’est plus prise en charge, et Node 24.0 à 24.8 ne suffit pas non plus. Exécutez node -v avant toute autre chose, car un échec au démarrage dû à un runtime non pris en charge ressemble à une installation défectueuse et incite à réinstaller le package plutôt que le runtime.

Cet article vous a-t-il été utile ?