Secrets et machines Synapse

Configuration du Coffre Pilotage IA, des machines et du journal dans DockSky App.

Menu Vue → Paramètres — sections en bas de page, après Accès IA.

---

Plan Pro requis

Les sections Coffre, Machines et Journal sont actives uniquement avec un plan Pro DockSky App.

Action	Plan gratuit	Plan Pro
Voir les sections (grisées)	Oui	Oui
Lister secrets / machines / journal via API	Oui	Oui
Créer, modifier, supprimer secrets	Non (403)	Oui
Créer, modifier, supprimer machines	Non (403)	Oui
Exécuter des commandes (synapse_exec)	Non (403)	Oui

Les comptes admin DockSky contournent cette restriction.

---

Coffre Pilotage IA (secrets)

Principe

Tu enregistres des paires nom → valeur dans un coffre personnel (HashiCorp Vault, montage synapse). Les valeurs sont stockées sous users/{ton_id}/{NOM}.

Dans les commandes envoyées à Synapse, tu références les secrets avec des placeholders :

mysql -uroot -p"{{MYSQL_ROOT}}" -e "SHOW DATABASES"

Le conteneur (ctn_mysql) se passe dans le champ container de synapse_exec — pas besoin de docker exec dans la commande (Synapse s'en charge côté serveur).

Le serveur remplace {{MYSQL_ROOT}} avant l'exécution. L'IA ne voit jamais les valeurs réelles.

:::tip Guillemets autour du secret Si le mot de passe contient des caractères spéciaux shell, entoure le placeholder : -p"{{MYSQL_ROOT}}". :::

Interface app

Élément	Description
Liste	Noms des secrets enregistrés (valeurs jamais affichées)
Champ NOM	Ex. DB_USER — converti automatiquement en majuscules à l'enregistrement
Champ Valeur	Masquée (champ mot de passe)
Enregistrer	Crée ou met à jour le secret
Supprimer la sélection	Supprime le secret sélectionné dans la liste

:::tip Conversion automatique des noms Dans l'app, si tu tapes db_user, il est enregistré en DB_USER. Via l'API directe, le nom doit déjà être en majuscules. :::

Règles de nommage (placeholders et secrets)

Règle	Valide	Invalide
Syntaxe placeholder	{{DB_USER}}	{{ DB_USER }}, {{db_user}}
Caractères du nom	A-Z, 0-9, _	minuscules, tirets, espaces
Longueur max	64 caractères	plus long
Premier caractère	Lettre majuscule (A-Z)	chiffre seul ({{1FOO}})
Valeur secrète	1 à 8192 caractères	vide

Exemples valides : DB_USER, MYSQL_PASSWORD, API_KEY_V2

Erreurs courantes

Erreur	Cause
Nom secret invalide	Minuscules, tiret ou format incorrect
Secret manquant pour le placeholder {{X}}	Secret non enregistré ou valeur vide
Placeholder invalide	Syntaxe {{…}} incorrecte dans la commande

---

Mes machines Synapse

Une machine est un profil d'exécution : elle indique où l'IA peut lancer des commandes (quels conteneurs Docker).

Interface app

Champ	Obligatoire	Description
slug	Oui	Identifiant utilisé dans synapse_exec (ex. docksky-vps) — converti en minuscules
Libellé	Oui	Nom lisible (ex. « VPS DockSky »)
Indication hôte	Non	Info indicative (ex. api.docksky.fr)
Conteneurs autorisés	Oui	Liste CSV (ex. docksky_api_dev,ctn_mysql)
Conteneur par défaut	Non	Utilisé si la commande n'en précise pas

Boutons :

• Enregistrer — crée ou met à jour selon que le slug existe déjà
• Nouvelle machine — vide le formulaire (défaut conteneur : docksky_api_dev)
• Supprimer la sélection — supprime la machine choisie

:::note Type de machine Dans Paramètres → Mes machines Synapse, choisis le type Docker local (infra DockSky) ou Agent distant (VPS perso avec synapse-agent). Pour un agent, le token d'enrôlement s'affiche une seule fois à la création — copie-le immédiatement. :::

Règles du slug

Règle	Exemple valide	Exemple invalide
Minuscules, chiffres, tirets	docksky-vps	DockSky_VPS
1 à 64 caractères	mon-vps-prod	slug vide
Commence et finit par alphanum	vps1	-vps

Règles des conteneurs

• Au moins un conteneur requis
• Noms : alphanumériques + _ . -, max 128 caractères chacun
• Doivent faire partie de la whitelist infra (SYNAPSE_ALLOWED_CONTAINERS côté serveur)

Si tu déclares un conteneur non autorisé sur l'infra DockSky, l'enregistrement est rejeté avec un message du type « Conteneurs non autorisés sur cette infra ».

Exemple de configuration

Champ	Valeur
slug	docksky-vps
Libellé	VPS DockSky production
Indication hôte	api.docksky.fr
Conteneurs	docksky_api_dev,ctn_mysql
Conteneur par défaut	docksky_api_dev

Commande MCP typique :

{
  "machine": "docksky-vps",
  "container": "ctn_mysql",
  "command": "mysql -uroot -p\"{{MYSQL_ROOT}}\" -e \"SHOW DATABASES\"",
  "timeout_seconds": 30
}

Exemple détaillé (appel JSON-RPC, réponse, REST) : Synapse et MCP dans Cursor.

---

Journal Synapse

Affiche les 30 dernières exécutions pilotées par l'IA ou l'API.

Pour chaque entrée :

• Date et heure
• Succès ✅ ou échec ❌
• Machine (slug) ou conteneur
• Template de commande (avec placeholders {{NOM}}, jamais les valeurs résolues)
• Extrait de stdout (tronqué, secrets masqués)

Le journal est en lecture seule dans l'app. L'API permet de paginer jusqu'à 200 entrées (GET /synapse/audit/logs?limit=50&offset=0).

---

Ordre de configuration recommandé

1. Secrets — enregistre d'abord tous les {{NOM}} dont tu auras besoin
2. Machine — déclare les conteneurs où ces commandes peuvent tourner
3. Token IA + MCP — connecte Cursor → voir Synapse et MCP
4. Test — une commande simple (echo test ou hostname)
5. Journal — vérifie que l'exécution apparaît et que les secrets sont masqués

---

API REST (utilisateurs avancés)

Base : https://api.docksky.fr/synapse — authentification Authorization: Bearer <JWT DockSky>.

Méthode	Chemin	Pro	Description
GET	/status	Non	{ enabled, plan_required, message }
GET	/secrets	Non	Liste des noms
PUT	/secrets/{name}	Oui	Corps : { "value": "…" }
DELETE	/secrets/{name}	Oui	Suppression
GET	/machines	Non	Liste des machines
POST	/machines	Oui	Création
PUT	/machines/{slug}	Oui	Mise à jour
DELETE	/machines/{slug}	Oui	Suppression
POST	/exec	Oui	Exécution shell
GET	/audit/logs	Non	Journal paginé