Déployer le SDK Python DeepSeek Harness sur un Mac cloud

Un script Python lancé dans le mauvais répertoire, une session qui disparaît après une déconnexion SSH ou un jeton API retrouvé dans un journal : ces symptômes indiquent généralement que le déploiement mélange code, état et responsabilité du processus.

La solution la plus rapide consiste à valider une seule tâche dans un espace de travail jetable, puis à figer le SDK et son runtime, isoler session_root, sécuriser les identifiants et tester la reprise après arrêt ou redémarrage avant de passer en exécution continue. Ne copiez pas simplement votre dossier local sur le Mac cloud et ne supposez pas que le SDK fournit un service de surveillance.

Cet article s’adresse à vous si vous automatisez des tâches de code avec Python, si vous devez exécuter des sessions DeepSeek Harness sur un Mac cloud destiné aux workloads d’agents, ou si vous devez réceptionner une machine distante dont la reprise doit être démontrable plutôt que déclarée « fonctionnelle ».

Dernière mise à jour : 18 août 2026. Les noms de paquets, le mode d’exécution Python, le runtime fourni et les prérequis macOS ont été vérifiés dans le dépôt officiel le 18 août 2026. Le projet reste en aperçu développeur et annonce des changements incompatibles possibles. Dépôt officiel DeepSeek Harness · documentation Python du dépôt

1. Définir le contrat d’exécution

Avant d’installer quoi que ce soit, classez votre scénario dans une seule catégorie :

• Script ponctuel : un processus démarre, traite une consigne, écrit un résultat, puis se ferme.
• Tâche planifiée : un ordonnanceur externe lance le script à des moments définis et doit éviter les doublons.
• Agent longue durée : le processus conserve des sessions, reçoit plusieurs demandes et doit être surveillé par une couche d’exploitation distincte.

Cette distinction détermine trois chemins qui ne doivent pas être confondus :

• cwd désigne le répertoire de travail utilisé par l’agent pour les fichiers et les commandes ;
• session_root désigne l’emplacement de persistance des sessions ;
• l’identifiant de session distingue une continuité de conversation et d’état d’une autre.

Le SDK expose cwd et runtime_cwd, tandis que session_root agit comme une commodité de haut niveau qui définit DSH_SESSION_ROOT. Le dépôt précise aussi que la persistance et la personnalité de déploiement relèvent de la configuration Cordis, et non d’une simple copie de fichiers Python. [Référence de l’API SDK et des chemins appliqués](https://github.com/deepseek-ai/deepseek-harness/blob/master/python/sdk/README.md)

Commencez par écrire un contrat de livraison très court :

Dépôt : /Users/agent/workspaces/demo-repo
État des sessions : /Users/agent/state/deepseek-harness
Processus responsable du lancement : ordonnanceur externe
Processus responsable de l’arrêt : ordonnanceur externe
Politique de reprise : lecture du journal avant toute nouvelle consigne
Politique de secret : variables d’environnement injectées au lancement

Cette étape évite trois coûts cachés. D’abord, un cwd implicite peut faire modifier le mauvais projet. Ensuite, un session_root placé dans le dépôt peut être copié, archivé ou supprimé avec le code. Enfin, un agent lancé dans un terminal interactif peut sembler stable jusqu’à la fermeture de la connexion distante, sans qu’aucun composant ne le redémarre.

Pour choisir votre environnement, utilisez les critères publiés dans notre guide sur le choix d’un environnement DeepSeek Harness pour Python : stabilité du chemin de travail, accès administrateur réellement disponible, persistance du disque et possibilité de reproduire la configuration.

2. Préparer une installation minimale

Le SDK Python officiel est distribué sous le nom deepseek-harness-sdk, mais le module importé s’appelle deepseek_harness. Son installation entraîne le paquet de runtime binaire correspondant, deepseek-harness-runtime-bin, avec la même version. Le client communique avec le runtime comme avec un sous-processus au moyen de JSON-RPC délimité par des retours à la ligne sur stdio. Présentation des paquets Python officiels

Sur un Mac Apple Silicon compatible, créez d’abord un environnement qui ne dépend pas de votre installation Python personnelle :

mkdir -p "$HOME/dsh-deploy/app"
mkdir -p "$HOME/dsh-deploy/state"
cd "$HOME/dsh-deploy/app"

python3 -m venv .venv
source .venv/bin/activate

python -m pip install --upgrade pip
python -m pip install deepseek-harness-sdk
python -m pip freeze > requirements.lock.txt

Ne remplacez pas la dernière commande par un simple commentaire dans votre documentation. Le fichier généré doit être conservé avec la livraison, car il permet de comparer l’environnement avant et après une mise à niveau.

L’installation normale n’exige pas Node.js : le runtime de production est fourni comme un exécutable autonome, et la roue macOS publiée contient le binaire ainsi que son auxiliaire natif nécessaire à certains outils de terminal. Le dépôt documente une cible macOS arm64 et une étiquette de roue correspondant à macOS 14.0 ou ultérieur. Il distingue explicitement ce mode de production du transport de développement basé sur une arborescence Node. Référence du paquet runtime et de ses transporteurs

Node.js reste toutefois nécessaire si vous choisissez de cloner le dépôt, d’installer ses dépendances et de construire depuis les sources. La documentation de ce chemin demande Node.js 22.19 ou ultérieur. Ne mélangez donc pas les deux modèles : roues préconstruites pour la production, ou source et Node.js pour contribuer, modifier ou vérifier le runtime.

À la fin de cette phase, le signal de réussite est précis :

• l’architecture du système correspond à la roue installée ;
• python -m pip freeze contient le SDK et son runtime ;
• le fichier de verrouillage est sauvegardé hors du répertoire de session ;
• aucun dépôt réel ni secret permanent n’est encore utilisé.

En cas d’échec, supprimez .venv, vérifiez l’architecture avec uname -m, puis recréez l’environnement. Ne commencez pas par installer globalement plusieurs versions de Node.js ou Python : cela masque souvent un mauvais canal de distribution.

3. Exécuter une première tâche vérifiable

La première tâche ne doit pas être « modifiez mon application de production ». Utilisez un dépôt jetable contenant un fichier texte, un petit script et une commande de test déterministe. Vous devez pouvoir comparer l’état avant et après.

Un exemple minimal :

from pathlib import Path
from deepseek_harness import DeepSeekHarness

workspace = Path("/Users/agent/workspaces/demo-repo")
state = Path("/Users/agent/state/deepseek-harness")

with DeepSeekHarness(
    cwd=str(workspace),
    session_root=str(state),
) as harness:
    result = harness.run(
        "Lisez README.md, créez un fichier validation.txt contenant "
        "la phrase VALIDATION_OK, puis exécutez le test local prévu."
    )
    print(result.final_response)
    print(result.session_id)
    print(result.finish_reason)

Les noms d’options exacts doivent être vérifiés contre la version installée avant mise en production. Le tutoriel officiel fournit le chemin ordonné d’installation et de première exécution ; le point important ici est la méthode d’acceptation, pas la reproduction d’un exemple avec une limite arbitraire de sortie. Tutoriel Python officiel

Votre dossier de preuve doit contenir au minimum :

1. la consigne envoyée ;
2. le chemin absolu du cwd ;
3. l’identifiant de session ;
4. la réponse finale et la raison de fin ;
5. la liste réelle des fichiers modifiés ;
6. la sortie de la commande de test.

Vérifiez séparément trois capacités. Une réponse du modèle ne prouve pas que l’agent peut écrire un fichier. Un fichier créé ne prouve pas que Bash est correctement disponible. Une commande Bash réussie ne prouve pas que la session est correctement persistée.

Si le test échoue, réduisez la tâche à une lecture de fichier, puis à une écriture contrôlée, puis à une commande sans effet destructif. Cette progression localise l’erreur entre le modèle, le chemin de travail, les permissions et le runtime JSON-RPC.

4. Séparer le code de l’état persistant

Le piège le plus fréquent sur un Mac cloud est de placer la session dans le même dossier que le dépôt. Cette organisation paraît simple, mais elle rend les sauvegardes ambiguës et augmente le risque de publier des journaux contenant des consignes, des chemins internes ou des résultats d’outils.

Adoptez plutôt cette séparation :

$HOME/dsh-deploy/app/        code, scripts, verrouillage Python
$HOME/dsh-deploy/workspaces/ dépôts de travail
$HOME/dsh-deploy/state/      journaux et données de session
$HOME/dsh-deploy/logs/       journaux du lanceur externe
$HOME/dsh-deploy/secrets/    uniquement si un fichier contrôlé est indispensable

Ne donnez pas le même identifiant à deux projets. Une session réutilisée conserve plus qu’un échange textuel : l’historique, le contexte et, selon la composition active, l’état Bash persistant peuvent continuer ensemble. La règle opérationnelle est donc la suivante :

• nouvelle tâche indépendante : nouveau session_id et nouveau sous-répertoire d’état ;
• suite directe d’une tâche interrompue : même session_id, même session_root, même dépôt ;
• changement de dépôt ou de permissions : nouvelle session, même si la consigne semble proche.

Le même identifiant peut continuer une tâche après le changement du processus Python si le journal persistant reste accessible et si la configuration du runtime demeure compatible. Il ne s’agit pas pour autant d’un verrou distribué : deux processus qui écrivent simultanément dans la même session doivent être considérés comme un scénario non validé tant que votre version et votre couche d’exploitation ne l’ont pas démontré.

Pour préparer une vraie stratégie de restauration, consultez aussi notre méthode de sauvegarde et restauration des sessions DeepSeek Harness. La sauvegarde doit couvrir les journaux et les fichiers de configuration nécessaires à la reprise, mais exclure les secrets en clair lorsque ceux-ci peuvent être réinjectés autrement.

5. Encadrer les secrets et le processus

Le runtime hérite des variables d’environnement DeepSeek Harness, notamment DEEPSEEK_BASE_URL et DEEPSEEK_API_KEY. Cette approche permet d’utiliser un endpoint réel ou un proxy local sans écrire le secret dans le script. Variables d’environnement reconnues par le SDK

Exemple de lancement contrôlé :

export DEEPSEEK_BASE_URL="https://api.deepseek.com"
export DEEPSEEK_API_KEY="à-injecter-par-le-lanceur"

exec "$HOME/dsh-deploy/app/.venv/bin/python" \
  "$HOME/dsh-deploy/app/run_agent.py"

Dans un environnement partagé, préférez un gestionnaire de secrets ou un fichier lisible uniquement par le compte de service. Ne placez jamais la clé dans requirements.lock.txt, dans un dépôt, dans une commande copiée dans un ticket ou dans un journal de débogage. Vérifiez également que les erreurs du lanceur ne recopient pas automatiquement tout l’environnement.

Le SDK conserve un sous-processus runtime réutilisable pendant la durée de vie du client. Cela facilite plusieurs appels dans un même processus, mais ne constitue pas une supervision système. Vous devez décider séparément qui :

• démarre le processus ;
• l’arrête après un délai ;
• capture les sorties et les erreurs ;
• effectue la rotation des journaux ;
• détecte un code de sortie anormal ;
• relance après un redémarrage macOS.

Un ordonnanceur, un service utilisateur macOS ou votre plateforme d’exploitation peut remplir ces fonctions, mais ne les attribuez pas automatiquement au SDK. La documentation officielle décrit le client et le runtime ; elle ne garantit pas un mécanisme intégré de haute disponibilité.

6. Valider la reprise et le retour arrière

Avant d’augmenter la durée de location, le nombre de tâches ou le niveau d’autonomie, exécutez cette recette d’acceptation :

• [ ] enregistrer le chemin absolu du dépôt et de session_root ;
• [ ] enregistrer l’architecture macOS, le Python utilisé et le contenu de requirements.lock.txt ;
• [ ] lancer une tâche jetable et conserver son session_id ;
• [ ] vérifier une modification de fichier et une commande Bash séparément ;
• [ ] arrêter volontairement le processus Python pendant une tâche ;
• [ ] relancer avec le même état, sans renvoyer automatiquement la consigne initiale ;
• [ ] lire le journal et déterminer si la modification avait déjà été validée ;
• [ ] simuler une coupure de connexion distante ;
• [ ] redémarrer le Mac cloud ;
• [ ] vérifier les permissions et les variables d’environnement après redémarrage ;
• [ ] reprendre la session avec le même identifiant uniquement si le projet et le contexte sont inchangés ;
• [ ] lancer une opération de lecture avant toute action d’écriture ;
• [ ] restaurer l’environnement verrouillé si une mise à niveau échoue.

Le point le plus important est d’éviter le doublon logique. Si le processus est mort après l’écriture du fichier mais avant la réception de votre accusé, relancer la même consigne peut produire une seconde modification, un second commit ou une nouvelle opération externe. La reprise doit donc commencer par l’observation du journal et de l’espace de travail, pas par une répétition aveugle.

Conservez enfin trois documents : la version installée, la portée de la sauvegarde et la procédure de retour arrière. Un déploiement est prêt lorsque quelqu’un d’autre peut reprendre la session sans deviner où se trouve le dépôt, quel identifiant utiliser ou quelles variables manquent.

Comparaison finale : poste local, Linux distant et Mac cloud

Le poste local reste préférable si vous avez besoin d’interfaces physiques, de périphériques audio ou vidéo connectés, d’un accès direct à des fichiers non transférables ou d’un développement quotidien interactif. Un serveur Linux peut être plus adapté à une charge homogène et à une exploitation déjà standardisée autour de conteneurs.

Mais une installation locale copiée manuellement présente souvent trois défauts pour un agent durable : l’environnement Python dérive, la session reste liée à un ordinateur qui n’est pas toujours disponible et la reprise après redémarrage dépend de connaissances implicites. Un serveur générique peut, de son côté, compliquer les workflows macOS, les tests d’applications Apple, le design et les outils créatifs qui dépendent de cet écosystème.

Si votre besoin est temporaire, si vous devez reproduire une configuration macOS pour une équipe ou si vous voulez d’abord valider le SDK avant d’acheter une machine dédiée, la location d’un Mac cloud auprès de MACGPU permet de séparer l’environnement de travail de votre poste principal. Commencez toutefois par appliquer la checklist de cet article : chemin stable, état isolé, secrets réinjectables et reprise vérifiée. Lorsque ces quatre éléments sont validés, vous pouvez consulter les solutions Mac cloud disponibles chez MACGPU et choisir une durée adaptée à votre phase de test ou d’exploitation.