Comment utiliser launchd pour activer le démarrage automatique de DeepSeek Harness en 2026 ?

La méthode recommandée consiste à utiliser un LaunchAgent exécuté par un compte utilisateur standard, et non à créer par défaut un service système root. Cette approche convient lorsque DeepSeek Harness doit retrouver une session utilisateur, un profil, un espace de travail et des fichiers de configuration après une connexion ou un redémarrage du Mac distant.

Cette semaine, nous vous conseillons de fixer d’abord quatre éléments — l’exécutable, le dossier de travail, le profil et la source de la clé API — puis de valider séparément le processus, le port, un appel modèle et la reprise après incident. Un fichier plist qui lance simplement une commande ne constitue pas encore une mise en production.

Cette procédure s’adresse à :

• Aux utilisateurs d’un Mac distant qui souhaitent retrouver DeepSeek Harness après un redémarrage ou une nouvelle ouverture de session.
• Aux ingénieurs plateforme qui doivent imposer une identité de processus, un emplacement de journaux et une méthode d’arrêt cohérente.
• Aux responsables de livraison qui veulent transformer « le programme démarre » en preuve reproductible de disponibilité.

DeepSeek Harness peut être utilisé comme interface Web, processus sans interface graphique ou entrée d’automatisation. Ces formes n’ont pas exactement le même cycle de vie. Une interface Web doit rester joignable et conserver un espace de travail cohérent ; une tâche Headless peut au contraire devoir démarrer, produire un résultat, puis quitter proprement.

Ne placez donc pas plusieurs usages dans le même LaunchAgent sans raison opérationnelle. Si l’interface Web et un traitement ponctuel partagent un même fichier plist, un redémarrage automatique peut relancer indéfiniment une tâche qui devait normalement se terminer. À l’inverse, un processus qui quitte après avoir terminé son travail ne doit pas être considéré comme défaillant uniquement parce que KeepAlive le relance.

Apple décrit launchd comme le mécanisme de gestion des agents et des démons sur macOS ; un agent est associé à l’utilisateur connecté, tandis qu’un démon système fonctionne dans un contexte indépendant de la session utilisateur. La différence est déterminante pour un outil qui dépend d’un profil, de fichiers personnels ou d’une interface accessible après connexion. Consultez la documentation Apple sur les LaunchAgents et LaunchDaemons ainsi que la présentation Apple des contextes utilisateur et root.

Avant d’écrire le moindre plist, consignez les informations suivantes dans un document de livraison :

• l’usage pris en charge : Web, Headless ou automatisation ;
• le chemin absolu de l’exécutable ;
• le dossier de travail ;
• le nom du profil réellement utilisé ;
• le compte macOS qui doit lancer le processus ;
• la méthode d’arrêt propre ;
• le port attendu, uniquement pour le mode Web ;
• le dossier de sortie et les fichiers dont dépend la tâche ;
• la méthode prévue pour lire la clé API sans l’inscrire dans le plist.

Le chemin absolu n’est pas un détail de présentation. Un terminal interactif peut connaître les chemins ajoutés par un gestionnaire de versions Node.js, alors que l’environnement lancé par launchd ne récupère pas forcément les mêmes fichiers de démarrage du shell. Cette différence explique une grande partie des erreurs « npx introuvable » ou « Node.js absent ».

L’emplacement généralement adapté à un agent propre à un utilisateur est :

~/Library/LaunchAgents/

Apple distingue cet emplacement des agents applicables à tous les utilisateurs et des démons installés au niveau système. La liste des dossiers de référence figure dans le guide Apple de gestion des scripts avec launchd.

Un LaunchAgent est généralement préférable lorsque DeepSeek Harness doit accéder à :

• un profil placé dans le répertoire personnel ;
• un espace de travail appartenant à l’utilisateur ;
• une session graphique ou une interface Web liée à la connexion ;
• des fichiers de configuration protégés par les droits de ce compte ;
• des outils installés dans l’environnement utilisateur.

Un LaunchDaemon peut rester pertinent pour un service réellement indépendant de toute session, mais le choisir simplement parce que le mot « démarrage » évoque le démarrage du système crée souvent plus de problèmes qu’il n’en résout. Le processus peut alors ne plus voir le profil attendu, perdre les variables préparées pour l’utilisateur ou écrire des fichiers appartenant à root. Le recours à root augmente également la portée d’une fuite de clé API et complique la maintenance.

Le plist ci-dessous est volontairement un gabarit, pas un fichier prêt à copier. Les chemins, l’identifiant du compte, le profil et la commande doivent être remplacés après vérification locale :

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.exemple.deepseek-harness</string>

    <key>ProgramArguments</key>
    <array>
        <string>/CHEMIN/ABSOLU/VERS/EXECUTABLE</string>
        <string>--profile</string>
        <string>PROFIL_A_VALIDER</string>
    </array>

    <key>WorkingDirectory</key>
    <string>/CHEMIN/ABSOLU/DU/PROJET</string>

    <key>RunAtLoad</key>
    <true/>

    <key>StandardOutPath</key>
    <string>/CHEMIN/LOGS/deepseek-harness.out.log</string>

    <key>StandardErrorPath</key>
    <string>/CHEMIN/LOGS/deepseek-harness.err.log</string>
</dict>
</plist>

N’ajoutez pas la clé API directement dans ProgramArguments, EnvironmentVariables ou une valeur enregistrée dans un dépôt. Un fichier plist peut être copié, sauvegardé ou lu par une personne qui n’a pas besoin de connaître le secret. Si DeepSeek Harness accepte une variable d’environnement, fournissez-la par un mécanisme protégé déjà validé dans votre environnement ; sinon, utilisez le trousseau ou un fichier de secrets dont les permissions sont strictement limitées au compte de service. Le guide Apple sur les fichiers plist de launchd doit servir de référence pour les clés de lancement, pas de justification pour exposer un secret.

Attention : KeepAlive ne signifie pas « reprendre une tâche interrompue ». Il demande à launchd de maintenir ou de relancer un processus selon les conditions indiquées. La reprise d’une tâche exige un état persistant, un point de contrôle et une logique de réconciliation propres à DeepSeek Harness.

Avant le chargement, contrôlez la propriété et les droits du fichier :

plutil -lint "$HOME/Library/LaunchAgents/com.exemple.deepseek-harness.plist"
ls -l "$HOME/Library/LaunchAgents/com.exemple.deepseek-harness.plist"

Le fichier doit être lisible par le compte qui l’utilise, mais il ne doit pas devenir un dépôt de secrets. Conservez le plist dans un emplacement versionné uniquement si sa copie exclut les valeurs sensibles.

Le problème le plus fréquent n’est pas launchd lui-même, mais la différence entre une session de terminal et l’environnement minimal d’un agent. Une commande comme :

npx -y paquet-exemple

peut fonctionner dans votre terminal, puis échouer dans le LaunchAgent parce que npx est installé dans un répertoire ajouté par un gestionnaire Node.js, un fichier de profil ou une configuration interactive.

Nous vous recommandons de déterminer les chemins depuis le compte qui exécutera réellement l’agent :

command -v node
command -v npx
node --version
npm --version

Remplacez ensuite node, npx ou dsh dans le plist par leur chemin absolu. Si l’entrée repose sur un script intermédiaire, utilisez un script contrôlé qui définit explicitement le PATH, le dossier de travail et les variables non sensibles. Le script doit échouer avec un message lisible lorsque l’exécutable manque ; il ne doit pas tenter silencieusement plusieurs versions.

Exemple de script de lancement, à adapter :

#!/bin/zsh
set -eu

export PATH="/CHEMIN/VERS/NODE/BIN:/usr/bin:/bin:/usr/sbin:/sbin"
export DEEPSEEK_PROFILE="PROFIL_A_VALIDER"

cd "/CHEMIN/ABSOLU/DU/PROJET"

exec "/CHEMIN/ABSOLU/VERS/dsh" web \
  --profile "$DEEPSEEK_PROFILE"

Le mot-clé exec permet de conserver une relation claire entre le processus déclaré par launchd et le programme réellement observé. N’ajoutez pas une chaîne de commandes complexe dans ProgramArguments en espérant que macOS l’interprète comme une ligne de shell ; si vous avez besoin de logique, placez-la dans un script contrôlé, avec des chemins fixes et des sorties explicites.

Si l’installation utilise npx, vérifiez aussi le comportement lors d’une absence de réseau ou d’un cache vide. Pour un service durable, une dépendance téléchargée à chaque lancement est moins prévisible qu’un paquet installé et versionné dans un environnement connu. Cette décision doit être prise avec la procédure de mise à niveau, et non au moment du dépannage.

Chargez l’agent depuis la session du compte concerné. Les commandes exactes peuvent varier selon la version de macOS ; l’objectif est de passer par launchctl, l’outil prévu par Apple pour charger et décharger les agents et démons.

launchctl bootstrap "gui/$(id -u)" \
  "$HOME/Library/LaunchAgents/com.exemple.deepseek-harness.plist"

launchctl print "gui/$(id -u)/com.exemple.deepseek-harness"

Le guide Apple sur launchctl rappelle que l’interaction opérationnelle avec launchd passe par cet outil. Après le chargement, ne commencez pas par activer une relance agressive. Commencez par établir pourquoi le processus démarre ou s’arrête.

Contrôlez l’identité du processus et le chemin utilisé :

pgrep -alf "deepseek|dsh|node"
ps -o user,pid,ppid,command -p PID_A_VERIFIER

Puis lisez les sorties :

tail -n 100 "/CHEMIN/LOGS/deepseek-harness.out.log"
tail -n 100 "/CHEMIN/LOGS/deepseek-harness.err.log"

Les journaux doivent répondre à quatre questions :

1. Le processus appartient-il au compte attendu ?
2. Le dossier de travail est-il celui du projet validé ?
3. Node.js, npx ou dsh sont-ils résolus avec le chemin prévu ?
4. L’erreur vient-elle du lancement, du profil, du réseau, de la clé API ou de l’application elle-même ?

Un processus qui redémarre constamment peut donner l’impression que le service est « surveillé », alors qu’il ne fait que produire une succession d’échecs. Nous préférons corriger le chemin, l’accès au dossier et les variables avant d’ajouter KeepAlive. Apple signale d’ailleurs qu’un programme géré par launchd ne doit pas se détacher lui-même ; sinon le superviseur peut croire que le processus est mort et tenter des relances incorrectes. Cette contrainte est expliquée dans la documentation Apple sur le comportement attendu des processus launchd.

Le démarrage du processus ne prouve pas que DeepSeek Harness est disponible. Nous séparons la validation en quatre preuves, car chacune élimine une catégorie de panne différente.

Pour le mode Web, vérifiez successivement :

• que le processus écoute sur l’adresse et le port prévus ;
• que l’interface répond depuis le réseau autorisé ;
• que le profil ouvre le bon espace de travail ;
• qu’une tâche modèle à faible risque peut être exécutée ;
• que la sortie ne révèle pas la clé API dans l’interface ou les journaux.

Pour examiner l’écoute locale :

lsof -nP -iTCP:PORT_ATTENDU -sTCP:LISTEN
curl -I "http://127.0.0.1:PORT_ATTENDU"

Une interface accessible depuis le navigateur mais incapable d’exécuter une tâche indique généralement que le processus Web est vivant, tandis qu’une dépendance d’exécution ne l’est pas. Les causes possibles incluent un profil différent, une clé API absente de l’environnement launchd, un dossier non accessible ou un chemin d’outil qui n’existe que dans le terminal interactif. Il faut alors comparer l’environnement réellement utilisé par l’agent avec celui du lancement manuel, sans imprimer la valeur de la clé.

Pour le mode Headless, la preuve est différente : la tâche doit retourner un code de sortie cohérent, créer l’artefact attendu et laisser une trace exploitable. Une commande terminée avec le code zéro mais sans fichier de sortie ne constitue pas une réussite. À l’inverse, un traitement qui produit l’artefact puis quitte avec un code non nul doit être analysé avant d’être placé sous relance automatique.

Si l’usage concerne l’audio, la vidéo ou le design, ajoutez au test un petit projet représentatif : lecture d’un fichier d’entrée, accès au dossier de ressources et écriture d’un résultat dans un emplacement durable. Les permissions d’un dossier de travail peuvent différer de celles d’un répertoire de code, en particulier lorsque les médias sont stockés sur un volume externe ou un partage distant.

Le tableau suivant aide à choisir le niveau de gestion adapté :

Cette distinction est cohérente avec le rôle décrit par Apple : un LaunchAgent s’exécute dans le contexte de l’utilisateur connecté, alors qu’un LaunchDaemon est conçu pour un service indépendant de l’utilisateur. La documentation Apple sur la conception des démons et agents précise également qu’un démon système ne doit pas dépendre directement de la présence d’un utilisateur.

Pour une procédure de contrôle plus large, nous vous conseillons de consulter notre guide sur la validation de l’interface Web de DeepSeek Harness, puis de conserver un compte rendu qui distingue port ouvert, authentification réussie et tâche effectivement exécutée.

La reprise d’un processus et la reprise d’une tâche sont deux sujets différents. launchd peut relancer une application, mais il ne connaît pas nécessairement l’état métier d’une opération interrompue. Sans identifiant de tâche, point de contrôle, verrou et logique de reprise dans DeepSeek Harness, un redémarrage peut recommencer un traitement ou créer un doublon.

Exécutez les scénarios dans cet ordre :

• [ ] Arrêter proprement DeepSeek Harness avec la méthode documentée, puis vérifier que le comportement attendu est bien observé.
• [ ] Simuler un arrêt anormal sur un environnement de test et vérifier si le LaunchAgent relance le processus ou le laisse arrêté.
• [ ] Se déconnecter puis rouvrir la session du compte propriétaire de l’agent.
• [ ] Redémarrer le Mac distant et confirmer que le compte, le profil et le dossier de travail restent cohérents.
• [ ] Après chaque étape, vérifier le processus, le journal d’erreur et l’état du port.
• [ ] Exécuter une tâche modèle à faible risque après la reprise.
• [ ] Pour une tâche longue, vérifier si l’état reprend, s’arrête avec une alerte ou recommence ; ne pas qualifier automatiquement ce résultat de « restauration ».
• [ ] Noter le moment de reprise observé et les conditions qui nécessitent une intervention humaine.

Pour l’interface Web, testez aussi l’accès depuis le poste distant autorisé, et non uniquement depuis 127.0.0.1. Un service peut être opérationnel localement mais inaccessible à cause de l’adresse d’écoute, du pare-feu, d’un tunnel ou de la règle réseau utilisée par le Mac distant. Cette vérification relève de l’accessibilité réseau, pas de la seule configuration launchd.

Pour une tâche Headless, conservez l’identifiant de l’exécution et le chemin de l’artefact. Si la reprise n’est pas native, documentez la limite : « le processus redémarre, mais la tâche exige une reprise applicative ». Cette formulation est plus exacte qu’une promesse générale de continuité.

Une configuration durable doit pouvoir être désactivée sans supprimer les journaux ni perdre le profil. Préparez une procédure de sortie avec l’identifiant exact du service :

launchctl bootout "gui/$(id -u)/com.exemple.deepseek-harness"

Conservez ensuite le plist précédent, le chemin de l’ancien exécutable et les journaux utiles. Lors d’une mise à niveau, arrêtez l’ancienne instance avant de charger la nouvelle. Vérifiez que la nouvelle version n’utilise pas le même port avec un second processus, et confirmez que son dossier d’état est compatible avec le profil existant.

La séquence de changement que nous recommandons est la suivante :

1. sauvegarder le plist et la procédure de retour arrière ;
2. arrêter l’ancienne instance ;
3. vérifier que le port est libéré ;
4. installer ou sélectionner le nouvel exécutable ;
5. modifier le chemin absolu et les paramètres nécessaires ;
6. charger le nouveau LaunchAgent ;
7. lire les journaux avant toute tâche réelle ;
8. exécuter le test Web ou Headless minimal ;
9. redémarrer le Mac distant ;
10. signer la livraison uniquement après la preuve de bout en bout.

Les services macOS modernes peuvent aussi utiliser les API de gestion des services et des éléments de connexion, mais cela ne signifie pas que DeepSeek Harness fournit un installateur natif correspondant. À ce stade, nous traitons donc launchd comme une capacité de gestion de processus macOS, et non comme une fonction officiellement intégrée à DeepSeek Harness. Toute commande d’installation annoncée ultérieurement devra être vérifiée dans la documentation et les versions réellement utilisées avant de remplacer cette procédure. Apple explique l’évolution des LaunchAgents et LaunchDaemons intégrés aux applications, mais cette documentation ne confirme pas un installateur propre à DeepSeek Harness.

Une installation locale peut convenir si le Mac reste allumé, connecté, accessible et administré par une équipe qui accepte de maintenir Node.js, les profils, les journaux et les mises à niveau. Elle devient moins intéressante lorsque la machine est arrêtée la nuit, qu’une session est régulièrement fermée, que le port doit rester disponible pour plusieurs utilisateurs ou que le poste sert aussi à la création audio, vidéo ou design.

Dans ce cas, le problème n’est pas seulement la commande launchd. Le Mac local impose une fenêtre de disponibilité incertaine, un accès distant à maintenir et un risque de concurrence avec les usages interactifs. Un environnement Mac distant préparé pour DeepSeek Harness permet de séparer le poste de travail quotidien du processus qui doit rester actif, à condition de vérifier la durée de location, les droits, le stockage et la procédure d’arrêt. Nous vous invitons à comparer cette approche dans notre guide de livraison et d’acceptation d’un Mac distant pour DeepSeek Harness.

Après le test de redémarrage, téléchargez ou copiez un modèle de procès-verbal sans valeur sensible : chemin de l’exécutable, compte, profil, port, emplacement des journaux, résultat de la tâche et décision de retour arrière. Si votre Mac actuel ne peut pas garantir une fenêtre d’occupation stable, passez ensuite à une étude de location d’un environnement Mac avec JEXCLOUD, en dimensionnant la durée selon les essais, la validation et la période de surveillance plutôt qu’en assimilant une relance de processus à une continuité complète du service.

• Mettre en place un LaunchAgent launchd pour un agent sur Mac distant
• Associer un tunnel SSH persistant à un LaunchAgent et à un contrôle de santé
• Diagnostiquer une interface Web DeepSeek Harness inaccessible sur macOS