Vous pouvez fermer votre PC après avoir lancé vos sessions. Agent Deck, tmux, Codex et Claude Code tournent sur un serveur Linux. Le même serveur héberge le collecteur OpenTelemetry, Prometheus et Grafana. Depuis n’importe quel appareil, un client SSH permet de reprendre une session et un navigateur permet de consulter le tableau. La génération reste assurée par les fournisseurs auxquels vous vous connectez.
Agent Deck affiche l’état de chaque session et son terminal. Grafana montre des compteurs d’activité rafraîchis à intervalles réguliers. Cet atelier suit une session Codex et une session Claude Code à la fois. Le tableau est fourni sous forme de script à copier sur le serveur.
- Agent Deck et tmuxCodex et Claude Code travaillent sur le serveur Linux dans des sessions séparées.
- OpenTelemetry CollectorLes clients envoient les métriques en HTTP sur la boucle locale du serveur.
- PrometheusRécupère les compteurs filtrés sur le réseau Docker et conserve leur historique.
- GrafanaInterroge Prometheus sur le serveur. Le navigateur accède au tableau via SSH.
1. Préparer le serveur et les accès
Partez d’une VM Debian ou Ubuntu avec systemd, SSH et Docker Engine et le plugin Compose installés depuis le dépôt officiel. L’exemple utilise Docker 28 ou plus récent, avec son démon système, le réseau bridge par défaut et les UID du conteneur sans remappage. Cette configuration réserve les ports publiés en boucle locale au serveur. Utilisez une VM dédiée à l’atelier et un disque local avec une marge au-delà du gigaoctet de blocs Prometheus. Seul l’administrateur de la VM utilise Docker. Comportement du mappage de ports Docker.
Sur le serveur, utilisez le compte administrateur pour créer le compte agents s’il n’existe pas. Installez votre clé SSH publique dans son compte. Vérifiez l’empreinte de l’hôte par un canal indépendant lors de la première connexion. Réservez à agents les dossiers de l’atelier et gardez ses droits distincts des groupes sudo et docker.
sudo apt update
sudo apt install ca-certificates curl git tmux less python3 openssl
sudo docker version --format '{{.Server.Version}}'
sudo docker compose version
sudo adduser --disabled-password --comment 'Agents de développement' agents
sudo loginctl enable-linger agents
enable-linger garde le gestionnaire systemd de ce compte disponible après la déconnexion. Nous vérifierons plus loin que tmux lui est rattaché. Documentation systemd de loginctl.
2. Préparer les fichiers de supervision
Restez sur le serveur avec le compte administrateur pour cette partie. Réservez un dossier neuf à Compose.
sudo mkdir /opt/agents-observability || exit 1
sudo chown "$(id -u):$(id -g)" /opt/agents-observability
cd /opt/agents-observability || exit 1
Enregistrez chaque bloc dans le fichier indiqué. Compose crée le réseau privé des conteneurs. L’hôte publie deux ports sur 127.0.0.1. Le port 4318 reçoit les métriques OTLP des CLI et 13000 ouvre Grafana à travers SSH. Prometheus scrape collector:9464 sur le réseau Docker.
compose.yaml
name: agent-dashboard
services:
collector:
image: otel/opentelemetry-collector-contrib:0.165.0
command: ["--config=/etc/otelcol-contrib/config.yaml"]
ports:
- "127.0.0.1:4318:4318"
volumes:
- ./collector.yaml:/etc/otelcol-contrib/config.yaml:ro
restart: unless-stopped
prometheus:
image: prom/prometheus:v3.16.0
command:
- --config.file=/etc/prometheus/prometheus.yml
- --storage.tsdb.path=/prometheus
volumes:
- ./prometheus.yaml:/etc/prometheus/prometheus.yml:ro
- prometheus-data:/prometheus
restart: unless-stopped
grafana:
image: grafana/grafana:13.3.1-ubuntu
ports:
- "127.0.0.1:13000:3000"
environment:
GF_SERVER_ROOT_URL: http://127.0.0.1:13000/
GF_SECURITY_ADMIN_PASSWORD__FILE: /run/secrets/grafana_admin_password
GF_AUTH_ANONYMOUS_ENABLED: "false"
GF_USERS_ALLOW_SIGN_UP: "false"
GF_ANALYTICS_REPORTING_ENABLED: "false"
GF_ANALYTICS_CHECK_FOR_UPDATES: "false"
GF_ANALYTICS_CHECK_FOR_PLUGIN_UPDATES: "false"
secrets: [grafana_admin_password]
volumes:
- ./datasource.yaml:/etc/grafana/provisioning/datasources/agents.yaml:ro
- ./dashboards.yaml:/etc/grafana/provisioning/dashboards/agents.yaml:ro
- ./grafana/dashboards/agents.json:/etc/grafana/dashboards/agents.json:ro
- grafana-data:/var/lib/grafana
restart: unless-stopped
secrets:
grafana_admin_password:
file: ./.secrets/grafana-admin-password
volumes:
prometheus-data:
grafana-data:
Les trois images sont épinglées à des versions publiées. Les volumes conservent les comptes Grafana et l’historique Prometheus. Images officielles OpenTelemetry · Installation Prometheus · Image officielle Grafana.
collector.yaml
receivers:
otlp:
protocols:
http:
endpoint: 0.0.0.0:4318
processors:
filter/agent_metrics:
error_mode: propagate
metric_conditions:
- 'not IsMatch(metric.name, "^(atelier[.]compteur|codex[.]tool[.]call|claude_code[.]token[.]usage|claude_code[.]code_edit_tool[.]decision)$")'
transform/minimize:
error_mode: propagate
metric_statements:
- 'keep_keys(resource.attributes, [])'
- 'keep_keys(datapoint.attributes, ["auth_mode", "originator", "session_source", "app.version", "model", "tool", "success", "type", "decision", "tool_name", "query_source", "source", "language", "speed", "effort"])'
delta_to_cumulative:
max_stale: 5m
max_streams: 2000
batch:
timeout: 1s
exporters:
prometheus:
endpoint: 0.0.0.0:9464
metric_expiration: 2m
without_scope_info: true
translation_strategy: UnderscoreEscapingWithoutSuffixes
service:
telemetry:
metrics:
level: none
pipelines:
metrics:
receivers: [otlp]
processors: [filter/agent_metrics, transform/minimize, delta_to_cumulative, batch]
exporters: [prometheus]
Le collecteur garde quatre noms de métriques et une liste d’attributs autorisés. Les attributs de ressource et les identifiants de compte ou de dépôt sont écartés avant le stockage. Ils peuvent transiter jusqu’au processus qui les filtre. Les noms d’outils peuvent eux-mêmes être internes. Faites cet essai avec un dépôt fictif, dans une VM de confiance, sans plug-in ni connecteur de travail. Le processeur delta_to_cumulative cumule en mémoire les compteurs envoyés sous forme de variations. Chaque série suppose un seul producteur actif. L’exporteur remplace les points par des tirets bas et conserve les noms sans suffixe ajouté, ce qui fixe les expressions du tableau. Conversion des compteurs · Règles de traduction Prometheus.
prometheus.yaml
global:
scrape_interval: 10s
scrape_timeout: 5s
storage:
tsdb:
retention:
time: 7d
size: 1GB
scrape_configs:
- job_name: otel-agents
static_configs:
- targets: ["collector:9464"]
Prometheus interroge le collecteur toutes les dix secondes. La rétention des blocs est limitée à sept jours ou à un gigaoctet. Le journal d’écriture et les compactages exigent de l’espace en plus. Stockage et rétention Prometheus.
datasource.yaml
apiVersion: 1
datasources:
- name: Prometheus Agents
uid: agents-prometheus
type: prometheus
access: proxy
url: http://prometheus:9090
isDefault: true
editable: false
jsonData:
timeInterval: 10s
dashboards.yaml
apiVersion: 1
providers:
- name: Atelier Agents IA
orgId: 1
folder: Agents IA
type: file
disableDeletion: true
allowUiUpdates: false
updateIntervalSeconds: 30
options:
path: /etc/grafana/dashboards
make-dashboard.py
Ce script génère le JSON que Grafana charge au démarrage. Exécutez-le depuis le dossier Compose après avoir copié les six fichiers. Appliquez 0644 aux fichiers de configuration sans secret afin que les services conteneurisés puissent les lire. Provisionnement Grafana.
import json
from pathlib import Path
datasource = {'type': 'prometheus', 'uid': 'agents-prometheus'}
charts = [
('Collecteur joignable', 'up{job="otel-agents"}', 'Scrape Prometheus'),
('Sonde de test', 'atelier_compteur{job="otel-agents"}', 'Valeur de test'),
('Codex · appels d’outils sur 5 min',
'sum by (tool, success) (increase(codex_tool_call{job="otel-agents"}[5m]))',
'{{tool}} · succès={{success}}'),
('Claude Code · tokens sur 5 min',
'sum by (type) (increase(claude_code_token_usage{job="otel-agents"}[5m]))',
'{{type}}'),
('Claude Code · décisions d’édition sur 5 min',
'sum by (tool_name, decision) (increase(claude_code_code_edit_tool_decision{job="otel-agents"}[5m]))',
'{{tool_name}} · {{decision}}'),
]
panels = []
for index, (title, query, legend) in enumerate(charts):
panels.append({
'id': index + 1,
'type': 'timeseries',
'title': title,
'datasource': datasource,
'gridPos': {'x': (index % 2) * 12, 'y': (index // 2) * 8, 'w': 12, 'h': 8},
'targets': [{'refId': 'A', 'datasource': datasource, 'expr': query, 'legendFormat': legend}],
})
dashboard = {
'uid': 'agents-live',
'title': 'Codex et Claude Code — activité serveur',
'schemaVersion': 41,
'time': {'from': 'now-30m', 'to': 'now'},
'refresh': '10s',
'editable': False,
'panels': panels,
}
path = Path('grafana/dashboards/agents.json')
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(json.dumps(dashboard, ensure_ascii=False, indent=2) + '\n', encoding='utf-8')
python3 make-dashboard.py
chmod 0644 compose.yaml collector.yaml prometheus.yaml datasource.yaml dashboards.yaml \
grafana/dashboards/agents.json
3. Valider, démarrer et tester avec une sonde
Créez le mot de passe initial de Grafana une seule fois. Réservez le fichier au compte numérique 472 de l’image Grafana Ubuntu. Compose le monte comme secret local et Grafana lit sa valeur au premier démarrage. Évitez de copier le dossier des secrets dans votre dépôt. Si vous réutilisez le volume Grafana, gérez le mot de passe depuis Grafana.
install -d -m 0700 .secrets
(umask 077; set -o noclobber; openssl rand -hex 24 > .secrets/grafana-admin-password) || exit 1
sudo chown 472:0 .secrets/grafana-admin-password
sudo chmod 0600 .secrets/grafana-admin-password
Validez les configurations sur le serveur. Exécutez les commandes une à une et corrigez toute erreur avant le démarrage.
sudo docker compose config --quiet
sudo docker compose pull
sudo docker compose run --rm --no-deps collector validate --config=/etc/otelcol-contrib/config.yaml
sudo docker compose run --rm --no-deps --entrypoint /bin/promtool prometheus \
check config /etc/prometheus/prometheus.yml
sudo docker compose run --rm --no-deps --entrypoint /bin/sh grafana \
-c 'test -r /run/secrets/grafana_admin_password'
sudo docker compose up -d
sudo docker compose ps
curl --max-time 5 --fail --silent --show-error http://127.0.0.1:13000/api/health
Envoyez une jauge fictive au récepteur OTLP. L’étiquette fictive user.email permet de vérifier que la règle de minimisation s’applique. Lancez la sonde juste avant de vérifier le tableau, car l’exporteur laisse expirer une série sans nouveau point.
python3 - <<'PY' | curl --max-time 5 --fail-with-body --silent --show-error \
-H 'Content-Type: application/json' --data-binary @- \
http://127.0.0.1:4318/v1/metrics
import json
import time
point = {
'timeUnixNano': str(time.time_ns()),
'asInt': '1',
'attributes': [{'key': 'user.email', 'value': {'stringValue': 'sonde@example.invalid'}}],
}
metric = {'name': 'atelier.compteur', 'gauge': {'dataPoints': [point]}}
print(json.dumps({'resourceMetrics': [{'scopeMetrics': [{'metrics': [metric]}]}]}))
PY
Vérifiez que la réponse OTLP ne déclare aucun point rejeté dans partialSuccess. Après un ou deux scrapes, interrogez Prometheus depuis son conteneur. up doit valoir 1, et la jauge doit valoir 1 sans attribut user_email. Ces deux contrôles vérifient le trajet jusqu’à Prometheus. Dans docker compose ps, vérifiez aussi que seuls 4318 et 13000 sont publiés, tous deux sur 127.0.0.1.
sudo docker compose exec -T prometheus /bin/promtool query instant \
http://127.0.0.1:9090 'up{job="otel-agents"}'
sudo docker compose exec -T prometheus /bin/promtool query instant \
http://127.0.0.1:9090 'atelier_compteur{job="otel-agents"}'
4. Ouvrir Grafana via SSH
Depuis l’appareil qui affiche le tableau, ouvrez un tunnel SSH vers le serveur. Remplacez serveur.exemple et le nom du compte par les vôtres. Le tunnel peut rester ouvert pendant que vous consultez le tableau. En le fermant, vous quittez l’affichage et les services continuent sur le serveur.
ssh -N -o ExitOnForwardFailure=yes -o ForwardAgent=no \
-L 127.0.0.1:13000:127.0.0.1:13000 agents@serveur.exemple
Dans le navigateur de cet appareil, ouvrez http://127.0.0.1:13000. Connectez-vous comme admin avec la valeur initiale lue depuis le serveur par l’administrateur (sudo cat /opt/agents-observability/.secrets/grafana-admin-password). Rangez-la dans votre gestionnaire de mots de passe. Ouvrez Dashboards, puis Agents IA et Codex et Claude Code — activité serveur. Le panneau Collecteur joignable doit s’afficher. Renvoyez la sonde si elle a expiré au bout de deux minutes.
5. Installer Agent Deck et les deux CLI
Les commandes suivantes s’exécutent dans une session SSH sur la VM sous le compte agents. Elles vérifient que le compte dispose du gestionnaire systemd utilisateur.
id
loginctl show-user agents --property=Linger --value
systemd-run --user --scope true
Attendez yes pour le maintien du gestionnaire et une sortie réussie du scope. Téléchargez les scripts d’installation officiels, relisez-les, puis lancez-les. Le script Agent Deck épinglé vérifie la somme publiée du binaire. Les CLI utilisent leur canal officiel. Notez les versions affichées pour pouvoir reproduire un diagnostic. Agent Deck v1.16.39 · Installation Codex · Installation Claude Code.
umask 077
install -d -m 0700 "$HOME/.local/bin" "$HOME/install-agents"
cd "$HOME/install-agents" || exit 1
curl -fsSL https://chatgpt.com/codex/install.sh -o install-codex.sh && \
curl -fsSL https://claude.ai/install.sh -o install-claude.sh && \
curl -fsSL https://raw.githubusercontent.com/asheshgoplani/agent-deck/v1.16.39/install.sh \
-o install-agent-deck.sh && \
less install-codex.sh install-claude.sh install-agent-deck.sh
sh install-codex.sh
bash install-claude.sh
bash install-agent-deck.sh --version 1.16.39 --skip-tmux-config
export PATH="$HOME/.local/bin:$PATH"
command -v codex claude agent-deck tmux
codex --version
claude --version
agent-deck version
Ajoutez l’export du PATH au fichier de démarrage du compte distant si nécessaire. Pour Codex, activez la connexion par code dans les paramètres de sécurité ChatGPT si elle est autorisée pour ce compte. Pour chaque fournisseur, ouvrez l’adresse affichée sur un appareil avec navigateur et suivez l’invite d’authentification. Gardez codes et sessions sur le compte distant. Auth Codex sur un serveur sans interface · Auth Claude Code.
codex login --device-auth
codex login status
claude auth login
claude auth status --text
6. Configurer les sessions et les exporteurs
Faites une copie de chaque configuration existante avant de la modifier. Créez ~/.config/agent-deck/config.toml sous agents ou utilisez le chemin défini par XDG_CONFIG_HOME. Intégrez les réglages aux tables présentes. Appliquez le mode scope avant le premier démarrage de tmux sous ce compte. Gardez l’approbation des actions dans chaque CLI. Référence Agent Deck.
[tmux]
launch_as = "scope"
[updates]
auto_update = false
auto_install = false
auto_restart = false
auto_update_remotes = false
check_enabled = false
manage_timer = false
[claude]
dangerous_mode = false
auto_mode = false
allow_dangerous_mode = false
[codex]
yolo_mode = false
[worktree]
run_repo_scripts = "never"
[recall]
enabled = false
Ajoutez les réglages de métriques à ~/.codex/config.toml sur le serveur. Avec un CODEX_HOME personnalisé, utilisez le fichier config.toml de ce répertoire. Modifiez les tables existantes sans les répéter. L’exporteur OTLP explicite est indépendant de l’option des mesures intégrées. Référence de configuration Codex · Métriques Codex.
[analytics]
enabled = false
[otel]
environment = "serveur-atelier"
exporter = "none"
trace_exporter = "none"
metrics_exporter = { otlp-http = { endpoint = "http://127.0.0.1:4318/v1/metrics", protocol = "binary" } }
log_user_prompt = false
Dans ~/.claude/settings.json, ajoutez ces clés à l’objet env. Sur un compte neuf, le fichier complet peut prendre cette forme. Le réglage utilisateur reste chargé quand Agent Deck démarre Claude Code dans une nouvelle session. Sur un environnement géré, vérifiez la destination et les options imposées par l’organisation avant l’essai. Réglages Claude Code · Métriques et variables OTLP.
{
"env": {
"CLAUDE_CODE_ENABLE_TELEMETRY": "1",
"OTEL_METRICS_EXPORTER": "otlp",
"OTEL_LOGS_EXPORTER": "none",
"OTEL_TRACES_EXPORTER": "none",
"OTEL_EXPORTER_OTLP_METRICS_PROTOCOL": "http/protobuf",
"OTEL_EXPORTER_OTLP_METRICS_ENDPOINT": "http://127.0.0.1:4318/v1/metrics",
"OTEL_METRIC_EXPORT_INTERVAL": "10000",
"OTEL_LOG_USER_PROMPTS": "0",
"OTEL_LOG_ASSISTANT_RESPONSES": "0",
"OTEL_LOG_TOOL_DETAILS": "0",
"OTEL_LOG_TOOL_CONTENT": "0",
"OTEL_LOG_RAW_API_BODIES": "0",
"OTEL_METRICS_INCLUDE_SESSION_ID": "false",
"OTEL_METRICS_INCLUDE_ACCOUNT_UUID": "false",
"OTEL_METRICS_INCLUDE_REPOSITORY": "false"
}
}
7. Créer deux sessions et vérifier la reprise après fermeture
Sous agents, utilisez un dépôt fictif dans un dossier neuf. Les worktrees séparent les deux branches. Les processus gardent les droits du compte Linux qui les lance.
atelier="$HOME/atelier-supervision"
mkdir -- "$atelier" || exit 1
git init -b main "$atelier/source"
cd "$atelier/source" || exit 1
printf '# Atelier de supervision\n' > README.md
git add -- README.md
git -c user.name='Atelier supervision' -c user.email='atelier@example.invalid' \
commit -m 'Créer la base de l’atelier'
git worktree add -b atelier-codex "$atelier/codex"
git worktree add -b atelier-claude "$atelier/claude"
export PATH="$HOME/.local/bin:$PATH"
agent-deck launch "$atelier/codex" -t atelier-codex -c codex
agent-deck launch "$atelier/claude" -t atelier-claude -c claude
agent-deck
Ouvrez une session avec Entrée, puis demandez à l’agent de lire README.md et de le résumer en une phrase. Détachez-vous avec Ctrl+Q. Faites l’essai dans l’autre session. Fermez SSH, reconnectez-vous et vérifiez que vous retrouvez les mêmes identifiants.
agent-deck list --json --no-archived
agent-deck session show --json atelier-codex
agent-deck session attach atelier-codex
Un tour peut continuer quand le client SSH est fermé. La reconnexion est le test qui le confirme sur votre serveur. Pour l’état instantané et une demande d’autorisation, ouvrez le terminal de l’agent. Les worktrees et les volumes gardent leurs données après un redémarrage de la VM. Ouvrez de nouveau les sessions tmux pour reprendre le travail. Commandes Agent Deck · Lecture des états de session.
8. Lire le tableau et diagnostiquer un panneau vide
- Collecteur joignable.
upindique que Prometheus arrive à lire le collecteur. La sonde confirme qu’un point OTLP a traversé la chaîne. - Codex. Les appels d’outils sont regroupés par nom et résultat. Le premier essai doit utiliser un outil, par exemple lire le fichier demandé.
- Claude Code. Les tokens sont regroupés par type. Pour tester le panneau des décisions d’édition, proposez un changement sur un fichier fictif et observez le résultat de la demande d’autorisation si le client en présente une.
Grafana rafraîchit la vue toutes les dix secondes. Le délai cumule l’export de la CLI, le traitement du collecteur et le scrape. Les courbes increase(...[5m]) demandent plusieurs points. Un panneau vide signale souvent un premier tour, une série jamais émise ou une série expirée. Les variations sont estimées sur la fenêtre et peuvent être fractionnaires. Conservez la limite d’un processus émetteur par outil pour éviter que deux compteurs de même identité se mélangent. Fonction increase de Prometheus.
Si up vaut zéro, commencez par les journaux du collecteur et de Prometheus sur le serveur. Si seul un panneau agent est vide, vérifiez la sonde, puis le chemin exact /v1/metrics, les réglages de la CLI et son redémarrage après modification. Les métriques indiquent l’activité instrumentée. Contrôlez le diff et les tests du dépôt pour vérifier le résultat du travail.
cd /opt/agents-observability || exit 1
sudo docker compose logs --tail=60 collector prometheus
9. Mettre à jour ou suspendre proprement
Gardez une copie des configurations et sauvegardez les volumes avant de changer une version. Pour une copie cohérente des volumes de cet atelier, arrêtez les services pendant la sauvegarde. Validez les nouveaux fichiers avec les commandes de la troisième étape, puis relancez Compose. En cas d’échec, reprenez les fichiers et tags précédents et restaurez la copie compatible du volume si le format a changé.
Pour une pause, terminez vos tours dans Agent Deck, puis arrêtez la supervision depuis le serveur. Compose conserve les volumes avec stop. Pour désactiver l’export des CLI, restaurez leurs configurations sauvegardées ou remettez leurs exporteurs de métriques à none, puis redémarrez les sessions concernées. Gérez le maintien du compte systemd séparément, une fois ses tâches terminées.
cd /opt/agents-observability || exit 1
sudo docker compose stop
# Pour reprendre la supervision
sudo docker compose up -d
Références vérifiées le 20 novembre 2026. Les étapes de sonde et de reconnexion servent à valider le déploiement sur votre serveur.