dstack

Aperçu

dstack provisionne et orchestre des charges de travail à travers les clouds GPU, Kubernetes, et en on-prem via des fleets.

Quand utiliser cette compétence :

• Exécuter ou gérer des environnements de développement, des tâches, ou des services sur dstack
• Créer, modifier, ou appliquer des configurations *.dstack.yml
• Gérer les fleets, les volumes, les passerelles, et vérifier les offres disponibles

Fonctionnement

dstack fonctionne via trois composants centraux :

1. dstack server - Peut s'exécuter localement, à distance, ou via dstack Sky (géré)
2. dstack CLI - Applique les configurations et gère ou inspecte les fleets, les exécutions, les logs, les événements, les volumes, les passerelles, et les offres ; il utilise les configurations de projet stockées dans ~/.dstack/config.yml, qui peuvent être gérées avec dstack project
3. dstack configuration files - Fichiers YAML se terminant par .dstack.yml

dstack apply affiche un plan et soumet les modifications de configuration. Pour les configurations d'exécution, il s'attache par défaut quand l'exécution atteint l'état running : il configure l'accès SSH, redirige les ports déclarés, et transmet les logs. Avec -d, il soumet et quitte.

Flux d'agent rapide (exécutions détachées)

1. Afficher le plan : echo "n" | dstack apply -f <config>
2. Si le plan est OK et l'utilisateur confirme, appliquer en détaché : dstack apply -f <config> -y -d
3. Vérifier l'état une fois : dstack ps -v
4. Si dev-environment ou tâche avec ports et en cours d'exécution : s'attacher pour afficher le lien IDE/les ports/l'alias SSH (l'agent s'attache en arrière-plan) ; demander d'ouvrir le lien
5. Si l'attachement échoue dans le sandbox : demander une escalade ; si non approuvée, demander à l'utilisateur d'exécuter dstack attach localement et de partager la sortie

CRITIQUE : Ne jamais proposer de commandes CLI dstack ou de syntaxes YAML qui n'existent pas.

• Utiliser uniquement les commandes CLI et la syntaxe YAML documentées ici ou vérifiées via --help
• En cas de doute sur une commande ou sa syntaxe, consulter les liens ou utiliser --help

NE JAMAIS faire ce qui suit :

• Inventer des flags CLI non documentés ici ou affichés dans --help
• Deviner les noms de propriétés YAML - vérifier dans les liens de référence de configuration
• Exécuter dstack apply pour les exécutions sans -d dans les contextes automatisés (bloque indéfiniment)
• Réessayer les commandes échouées sans résoudre l'erreur sous-jacente
• Résumer ou reformater les sorties CLI tabulaires - les afficher telles quelles
• Utiliser echo "y" | quand le flag -y est disponible
• Supposer qu'une commande a réussi sans vérifier la sortie pour les erreurs

Directives d'exécution d'agent

Précision des sorties

• NE JAMAIS reformater, résumer, ou paraphraser les sorties CLI. Afficher les tableaux, les sorties d'état, et les messages d'erreur exactement comme retournés.
• Lors de l'affichage des résultats de commande, utiliser des blocs de code pour préserver le formatage.
• Si la sortie est tronquée en raison de la longueur, l'indiquer clairement (par ex. "Output truncated. Full output shows X entries.").

Vérification avant exécution

• En cas de doute sur un flag CLI ou une propriété YAML, exécuter d'abord dstack <command> --help.
• Ne jamais deviner ni inventer de flags. Exemples de commandes de vérification :

  dstack --help                               # List all commands
  dstack apply -h <configuration type>        # Flags for apply per configuration type (dev-environment, task, service, fleet, etc)
  dstack fleet --help                         # Fleet subcommands
  dstack ps --help                            # Flags for ps

• Si une commande ou un flag n'est pas documenté, il n'existe pas.

Timing des commandes et gestion des confirmations

Commandes qui diffusent indéfiniment au premier plan :

• dstack attach
• dstack apply sans -d pour les exécutions
• dstack ps -w

Les agents doivent éviter de bloquer : utiliser -d, les timeouts, ou l'attachement en arrière-plan. Quand l'attachement est nécessaire, l'exécuter en arrière-plan par défaut (nohup ...), mais le décrire à l'utilisateur simplement comme « attach » sauf s'il demande une session au premier plan en direct. Préférer dstack ps -v et faire un polling en boucle si l'utilisateur souhaite regarder l'état.

Toutes les autres commandes : Utiliser un timeout de 10-60s. La plupart se terminent dans cette plage. Pendant l'attente, surveiller la sortie - elle peut contenir des erreurs, des avertissements, ou des invites nécessitant une attention.

Gestion des confirmations :

• dstack apply, dstack stop, dstack fleet delete nécessitent une confirmation
• Utiliser le flag -y pour auto-confirmer quand l'utilisateur a déjà approuvé
• Pour dstack stop, toujours utiliser -y après la confirmation de l'utilisateur pour éviter les invites interactives
• Utiliser echo "n" | pour prévisualiser le plan dstack apply sans exécuter (éviter echo "y" |, préférer -y)

Meilleures pratiques :

• Préférer modifier les fichiers de configuration plutôt que de passer des paramètres à dstack apply (sauf exception)
• Quand l'utilisateur confirme les opérations de suppression/arrêt, utiliser le flag -y pour ignorer les invites de confirmation

Suivi des exécutions détachées (après -d)

Après la soumission d'une exécution avec -d (dev-environment, tâche, service), d'abord déterminer si la soumission a échoué. Si la sortie d'apply affiche des erreurs (validation, aucune offre, etc.), arrêter et afficher l'erreur.

Si l'exécution a été soumise, faire une vérification d'état rapide avec dstack ps -v, puis guider l'utilisateur à travers les prochaines étapes pertinentes : Si vous devez inciter aux prochaines actions, être explicite sur l'étape dstack et la commande (éviter les questions vagues). Quand on parle à l'utilisateur, désigner l'action comme « attach » (pas « background attach »).

• Surveiller l'état : Rapporter l'état actuel (provisioning/pulling/running/finished) et proposer de continuer à regarder. Faire un polling de dstack ps -v tous les 10-20s si l'utilisateur souhaite des mises à jour.
• S'attacher en exécution : Pour les agents, exécuter l'attachement en arrière-plan par défaut pour que la session ne bloque pas. L'utiliser pour capturer les liens IDE/alias SSH ou activer la redirection de ports ; quand décrivant l'action à l'utilisateur, dire simplement « attach ».
• Environnements de développement ou tâches avec ports : Une fois running, s'attacher pour afficher le lien IDE/la redirection de ports/l'alias SSH, puis demander s'il faut ouvrir le lien IDE. Ne jamais ouvrir les liens sans approbation explicite.
• Services : Préférer utiliser les endpoints de service. S'attacher uniquement si l'utilisateur demande explicitement la redirection de ports ou la lecture complète des logs.
• Tâches sans ports : Par défaut utiliser dstack logs pour le progrès ; s'attacher uniquement si la lecture complète des logs est requise.

Comportement de l'attachement (bloquant vs non-bloquant)

dstack attach s'exécute jusqu'à interruption et bloque le terminal. Les agents doivent éviter les blocages indéfinis. Si un attachement bref est nécessaire, utiliser un timeout pour capturer la sortie initiale (lien IDE, alias SSH) puis se détacher.

Note : dstack attach écrit les informations d'alias SSH sous ~/.dstack/ssh/config (et peut mettre à jour ~/.ssh/config) pour activer ssh <run name>, les connexions IDE, la redirection de ports, et les logs en temps réel (dstack attach --logs). Si le sandbox ne peut pas y écrire, l'alias ne sera pas créé.

Garde-fou des permissions : Si dstack attach échoue en raison des permissions du sandbox, demander une escalade des permissions pour l'exécuter en dehors du sandbox. Si l'escalade n'est pas approuvée ou si l'attachement échoue toujours, demander à l'utilisateur d'exécuter dstack attach localement et de partager la sortie du lien IDE/alias SSH.

Attachement en arrière-plan (non-bloquant par défaut pour les agents) :

nohup dstack attach <run name> --logs > /tmp/<run name>.attach.log 2>&1 & echo $! > /tmp/<run name>.attach.pid

Puis lire la sortie :

tail -n 50 /tmp/<run name>.attach.log

Proposer un suivi en direct uniquement si demandé :

tail -f /tmp/<run name>.attach.log

Arrêter l'attachement en arrière-plan (préféré) :

kill "$(cat /tmp/<run name>.attach.pid)"

Si le fichier PID est manquant, se rabattre sur une correspondance spécifique (éviter de tuer tous les attachements) :

pkill -f "dstack attach <run name>"

Pourquoi cela aide : cela garde la session d'attachement active (y compris la redirection de ports) tandis que l'agent reste utilisable. Les liens IDE et les instructions SSH apparaissent dans le fichier log -- les afficher et demander s'il faut ouvrir le lien (open "<link>" sur macOS, xdg-open "<link>" sur Linux) uniquement après approbation explicite.

Si l'attachement en arrière-plan échoue dans le sandbox (permissions d'écriture sur ~/.dstack ou ~/.ssh, timeouts), demander une escalade pour exécuter l'attachement en dehors du sandbox. Si non approuvé, demander à l'utilisateur d'exécuter l'attachement localement et de partager le lien IDE/alias SSH.

Interprétation des demandes utilisateur

« Exécuter quelque chose » : Quand l'utilisateur demande d'exécuter une charge de travail (environnement de développement, tâche, service), utiliser dstack apply avec la configuration appropriée. Note : dstack run ne supporte que dstack run get --json pour récupérer les détails d'exécution -- il ne peut pas démarrer les charges de travail.

« Se connecter à » ou « ouvrir » un environnement de développement : Si un environnement de développement s'exécute déjà, utiliser dstack attach <run name> --logs (l'agent l'exécute en arrière-plan par défaut) pour afficher l'URL IDE (cursor://, vscode://, etc.) et l'alias SSH. Si l'attachement en sandbox échoue, demander une escalade ou demander à l'utilisateur d'exécuter l'attachement localement et de partager le lien.

Types de configuration

dstack supporte les configurations d'exécution (environnements de développement, tâches, et services) et les configurations d'infrastructure (fleets, volumes, et passerelles). Les fichiers de configuration peuvent être nommés <name>.dstack.yml ou simplement .dstack.yml.

Paramètres courants : Toutes les configurations d'exécution (environnements de développement, tâches, services) supportent de nombreux paramètres incluant :

• Intégration Git : Cloner les repos automatiquement (repo) ou monter les repos existants (repos)
• Upload de fichiers : Charger les fichiers locaux (files; voir la documentation des concepts pour des exemples)
• Support Docker : Utiliser des images Docker personnalisées (image); utiliser docker: true si vous voulez utiliser Docker depuis l'intérieur du conteneur (backends basés VM uniquement)
• Environnement : Définir les variables d'environnement (env), souvent via .envrc. Les secrets sont supportés mais moins courants.
• Stockage : Volumes réseau persistants (volumes), spécifier la taille du disque
• Ressources : Définir les exigences GPU, CPU, mémoire, et disque

Meilleures pratiques :

• Préférer donner aux configurations une propriété name pour une gestion plus facile
• Quand les configurations ont besoin d'identifiants (clés API, tokens), lister uniquement les noms de variables d'environnement dans la section env (par ex. - HF_TOKEN), pas les valeurs. Recommander de stocker les valeurs réelles dans un fichier .envrc à côté de la configuration, appliquées via source .envrc && dstack apply.
• python et image s'excluent mutuellement dans les configurations d'exécution. Si image est défini, ne pas définir python.

Politique d'intention pour files et repos

Utiliser files et repos uniquement quand l'utilisateur a l'intention d'utiliser les fichiers locaux/repo à l'intérieur de l'exécution.

• Si l'utilisateur demande d'utiliser le code/données/config du projet dans l'exécution, alors ajouter files ou repos selon le cas.
• Si c'est totalement flou de savoir si les fichiers ou repos doivent être montés, poser une seule question de clarification explicite ou par défaut ne pas monter.

Guidance files :

• Les chemins relatifs sont valides et préférés pour les fichiers de projet locaux.
• Un chemin files relatif est placé sous le working_dir de l'exécution (par défaut ou défini par l'utilisateur).

Guidance repos + image/répertoire de travail :

• Avec les images Docker non-par défaut, préférer les cibles de montage absolues explicites pour repos (par ex. .:/dstack/run).
• Quand on définit un chemin de montage de repo explicite, également définir working_dir au même chemin.
• Raison : les images personnalisées peuvent avoir un répertoire de travail par défaut différent/non-vide, et monter un repo dans un chemin non-vide peut échouer.
• Avec les images par défaut dstack, le working_dir par défaut est déjà /dstack/run.

1. Environnements de développement

Utiliser pour : Développement interactif avec intégration IDE (VS Code, Cursor, etc.).

type: dev-environment
name: cursor

python: "3.12"
ide: vscode

resources:
  gpu: 80GB

Documentation conceptuelle | Référence de configuration

2. Tâches

Utiliser pour : Jobs batch, exécutions d'entraînement, fine-tuning, applications web, toute charge de travail exécutable.

Fonctionnalités clés : Entraînement distribué (multi-nœud) et redirection de ports pour les applications web.

type: task
name: train

python: "3.12"
env:
  - HUGGING_FACE_HUB_TOKEN
commands:
  - uv pip install -r requirements.txt
  - uv run python train.py
ports:
  - 8501  # Optional: expose ports for web apps

resources:
  gpu: A100:40GB:2

Redirection de ports : Quand vous spécifiez ports, dstack apply les redirige vers localhost quand attaché. Utiliser dstack attach <run name> pour se reconnecter et restaurer la redirection de ports. Le nom d'exécution devient un alias SSH (par ex. ssh <run name>) pour un accès direct.

Entraînement distribué : Les tâches multi-nœud sont supportées (par ex. via nodes) et nécessitent des fleets qui supportent la communication inter-nœud (voir placement: cluster dans les fleets).

Documentation conceptuelle | Référence de configuration

3. Services

Utiliser pour : Déployer des modèles ou des applications web comme endpoints de production.

Fonctionnalités clés : Serving de modèles compatible OpenAI, auto-scaling (RPS/file d'attente), passerelles personnalisées avec HTTPS.

type: service
name: llama31

python: "3.12"
env:
  - HF_TOKEN
commands:
  - uv pip install vllm
  - uv run vllm serve meta-llama/Meta-Llama-3.1-8B-Instruct
port: 8000
model: meta-llama/Meta-Llama-3.1-8B-Instruct

resources:
  gpu: 80GB
  disk: 200GB

Endpoints de service :

• Sans passerelle : <server URL>/proxy/services/<project name>/<run name>/
• Avec passerelle : https://<run name>.<gateway domain>/
• Authentification : Sauf si auth est false, inclure Authorization: Bearer <user token> sur les demandes de service.
• Endpoint de modèle : Si model est défini, service.model.base_url de dstack run get <run name> --json fournit l'endpoint du modèle. Pour les modèles compatibles OpenAI (par défaut, sauf si format est défini autrement), ce sera service.url + /v1.
• Exemple (avec passerelle) :

  curl -sS -X POST "https://<run name>.<gateway domain>/v1/chat/completions" \
    -H "Authorization: Bearer <user token>" \
    -H "Content-Type: application/json" \
    -d '{"model":"<model name>","messages":[{"role":"user","content":"Hello"}],"max_tokens":64}'

Documentation conceptuelle | Référence de configuration

4. Fleets

Utiliser pour : Provisionner préalablement l'infrastructure pour les charges de travail, gérer les serveurs GPU on-prem, créer des pools d'instances auto-scalables.

type: fleet
name: my-fleet
nodes: 0..2

resources:
  gpu: 24GB..
  disk: 200GB

spot_policy: auto # other values: spot, on-demand
idle_duration: 5m

Provisionnement à la demande : Quand nodes est une plage (par ex. 0..2), dstack crée un modèle et provisionne les instances à la demande dans le min/max. Utiliser idle_duration pour terminer les instances inactives.

Charges de travail distribuées : Utiliser placement: cluster pour les fleets destinés aux tâches multi-nœud qui nécessitent une mise en réseau inter-nœud.

Fleet SSH (on-prem ou pré-provisionné) :

type: fleet
name: on-prem-fleet

ssh_config:
  user: ubuntu
  identity_file: ~/.ssh/id_rsa
  hosts:
    - 192.168.1.10
    - 192.168.1.11

Documentation conceptuelle | Référence de configuration

5. Volumes

Utiliser pour : Stockage persistant pour les datasets, les checkpoints de modèles, les artefacts d'entraînement.

type: volume
name: my-volume

backend: aws
region: us-east-1

resources:
  disk: 500GB

Volumes d'instance (locaux, éphémères, souvent optionnels) :

type: dev-environment
# ... other config
volumes:
  - instance_path: /dstack-cache/pip
    path: /root/.cache/pip
    optional: true
  - instance_path: /dstack-cache/huggingface
    path: /root/.cache/huggingface
    optional: true

Montage de volumes : Utiliser volumes dans les environnements de développement, les tâches, et les services. Les volumes réseau persistent indépendamment ; les volumes d'instance sont liés au cycle de vie de l'instance.

Documentation conceptuelle | Référence de configuration

6. Passerelles

Utiliser pour : Les passerelles sont optionnelles pour les endpoints de service basiques. Elles sont requises quand un service utilise l'auto-scaling ou les limites de débit, a besoin de HTTPS sur un domaine personnalisé, nécessite des WebSockets, ou ne peut pas fonctionner avec le préfixe de chemin proxy du serveur.

type: gateway
name: my-gateway

backend: aws
region: us-east-1
domain: example.com

Documentation conceptuelle | Référence de configuration

Commandes CLI essentielles

Appliquer les configurations

Comportement important :

• dstack apply affiche un plan avec les coûts estimés et peut demander une confirmation
• En mode attaché (par défaut), le terminal bloque et affiche la sortie
• En mode détaché (-d), il soumet et quitte sans s'attacher

Flux de travail pour appliquer les configurations d'exécution (dev-environment, tâche, service) :

1. Afficher le plan :

   echo "n" | dstack apply -f config.dstack.yml

   Afficher la sortie COMPLÈTE incluant le tableau des offres et l'estimation des coûts. Ne PAS résumer ou reformater.

2. Attendre la confirmation de l'utilisateur. Ne PAS procéder si :

   • La sortie affiche « No offers found » ou des erreurs similaires
   • La sortie affiche des erreurs de validation
   • L'utilisateur n'a pas explicitement confirmé

3. Exécuter (uniquement après confirmation de l'utilisateur) :

   dstack apply -f config.dstack.yml -y -d

4. Vérifier le statut d'apply :

   dstack ps -v

Flux de travail pour l'infrastructure (fleet, volume, gateway) :

1. Afficher le plan :

   echo "n" | dstack apply -f infra.dstack.yml

   Afficher la sortie COMPLÈTE. Ne PAS résumer ou reformater.

2. Attendre la confirmation de l'utilisateur.

3. Exécuter :

   dstack apply -f infra.dstack.yml -y

4. Vérifier : Utiliser dstack fleet, dstack volume, ou dstack gateway respectivement.

Gestion des fleets

# Create/update fleet
dstack apply -f fleet.dstack.yml

# List fleets
dstack fleet

# Get fleet details
dstack fleet get my-fleet

# Get fleet details as JSON (for troubleshooting)
dstack fleet get my-fleet --json

# Delete entire fleet (use -y when user already confirmed)
dstack fleet delete my-fleet -y

# Delete specific instance from fleet (use -y when user already confirmed)
dstack fleet delete my-fleet -i <instance num> -y

Surveiller les exécutions

# List all runs
dstack ps

# Verbose output with full details
dstack ps -v

# JSON output (for troubleshooting/scripting)
dstack ps --json

# Get specific run details as JSON
dstack run get my-run-name --json

S'attacher aux exécutions

# Attach and replay logs from start (preferred, unless asked otherwise)
dstack attach my-run-name --logs

# Attach without replaying logs (restores port forwarding + SSH only)
dstack attach my-run-name

Afficher les logs

# Stream logs (tail mode)
dstack logs my-run-name

# Debug mode (includes additional runner logs)
dstack logs my-run-name -d

# Fetch logs from specific replica (multi-node runs)
dstack logs my-run-name --replica 1

# Fetch logs from specific job
dstack logs my-run-name --job 0

Arrêter les exécutions

# Stop specific run (use -y after user confirms)
dstack stop my-run-name -y

# Abort (force stop)
dstack stop my-run-name --abort

Lister les offres

Les offres représentent les configurations d'instance disponibles qui correspondent aux exigences de ressources. Si --fleet est omis, dstack offer vérifie tous les backends configurés. Lister les offres ne crée pas de capacité ; la soumission d'une exécution nécessite toujours au moins une fleet qui peut provisionner ou réutiliser des instances correspondantes. Utiliser --fleet pour inspecter les offres disponibles via des fleets spécifiques.

# Filter by specific backend
dstack offer --backend aws

# Filter by GPU type
dstack offer --gpu A100

# Filter by GPU memory
dstack offer --gpu 24GB..80GB

# Combine filters
dstack offer --backend aws --gpu A100:80GB

# Limit to a specific fleet
dstack offer --fleet my-fleet

# Combine offers from multiple fleets
dstack offer --fleet my-fleet --fleet other-fleet

# JSON output (for troubleshooting/scripting)
dstack offer --json

Avec un seul --fleet, dstack offer affiche les offres disponibles via ce fleet. Avec plusieurs --fleet, il combine les offres disponibles via les fleets sélectionnés. Les offres identiques de backend sont affichées une fois, tandis que les instances existantes correspondantes restent séparées.

Max offers : Par défaut, dstack offer retourne les N premières offres (la sortie inclut aussi le nombre total). Utiliser --max-offers N pour augmenter la limite.

Groupement : Préférer --group-by gpu pour la sortie agrégée à travers toutes les offres, pas --max-offers. Les autres champs supportés sont backend, region, et count ; region nécessite backend.

Dépannage

Lors du diagnostic des problèmes avec les charges de travail ou l'infrastructure dstack :

1. Utiliser la sortie JSON pour une inspection détaillée :

   dstack fleet get my-fleet --json
   dstack run get my-run --json
   dstack ps -n 10 --json
   dstack offer --json

2. Vérifier le statut d'exécution détaillé :

   dstack ps -v

3. Examiner les logs avec la sortie de débogage :

   dstack logs my-run -d

4. S'attacher avec relecture des logs :

   dstack attach my-run --logs

Problèmes courants :

• Aucune offre : Vérifier dstack offer; si on soumet une exécution, s'assurer qu'au moins une fleet peut provisionner ou réutiliser des instances correspondantes
• Aucune fleet : S'assurer qu'au moins une fleet est créée
• Erreurs de configuration : Valider la syntaxe YAML ; vérifier la sortie dstack apply pour les erreurs spécifiques
• Timeouts de provisionnement : Utiliser dstack ps -v pour voir l'état de provisionnement ; considérer spot vs on-demand
• Problèmes de connexion : Vérifier le statut du serveur, vérifier l'authentification, s'assurer de l'accès réseau aux backends

Quand des erreurs se produisent :

1. Afficher le message d'erreur complet inchangé
2. Ne PAS réessayer la même commande sans résoudre l'erreur
3. Se référer au guide de dépannage pour des conseils

Ressources supplémentaires

Documentation principale :

• Aperçu
• Installation
• Démarrage rapide

Concepts supplémentaires :

• Secrets
• Projets
• Métriques
• Événements

Guides :

• CLI & API
• Déploiement du serveur

Exemples spécifiques aux accélérateurs :

• AMD
• Google TPU
• Tenstorrent

Documentation complète : https://dstack.ai/llms-full.txt