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.

---

Accès Synapse (Bandeau)

Tout compte DockSky App (plan Free inclus) active Pilotage IA avec le plan Synapse free et des quotas:

Quota	Free Synapse	Pro Synapse
Exécutions / mois	250	25 000
Secrets	5	500
Machines	1	10

Action	Free Bandeau	Pro Bandeau
Voir les sections Paramètres	Oui	Oui
Créer / modifier secrets et machines (app ou API)	Oui (quotas)	Oui
Exécuter via API REST (/synapse/exec)	Oui (quotas)	Oui
Exécuter via MCP synapse_exec	Non (scope Pro)	Oui

Les comptes admin contournent les restrictions.

---

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 (ma_base_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. mon-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. mon_app,ma_base_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 : mon_app)
• 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	mon-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	mon-vps
Libellé	Mon serveur de prod
Indication hôte	api.example.com
Conteneurs	mon_app,ma_base_mysql
Conteneur par défaut	mon_app

Commande MCP typique :

{
  "machine": "mon-vps",
  "container": "ma_base_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é