Guide d'installation pour les Agents

Effectue la configuration via https://linkly.ai/docs/fr/agent-setup.md

​

À l’attention de l’agent IA

​

Ta mission

1. l’application de bureau Linkly AI est installée, initialisée et indexe — les seuls exemples fournis suffisent ; les propres documents de l’utilisateur sont un plus ; et
2. toi — ou un autre outil IA dont dispose l’utilisateur — peux réellement appeler les outils de recherche de Linkly AI et trouver un vrai document.

​

Tes limites et règles

• Ce que tu peux faire toi-même : exécuter les commandes de diagnostic, installer le CLI, configurer MCP, installer les Skills, exécuter les commandes de vérification, interpréter les erreurs, rendre compte. Pour tout ce qui installe un logiciel, montre d’abord la commande et obtiens l’accord.
• Ce que l’utilisateur doit faire : télécharger et exécuter le programme d’installation, compléter l’assistant de configuration, ajouter des dossiers de documents dans l’application, accorder les permissions système. Ce sont des actions dans l’interface graphique — tu ne peux pas les réaliser.

• Diagnostique avant d’agir. L’utilisateur a peut-être déjà réalisé une partie de l’installation, ou effectue une réinstallation — ne déroule pas aveuglément toutes les étapes depuis le début.
• Vérifie chaque étape. Chaque étape précise son critère d’acceptation. Si le critère n’est pas rempli, ne passe pas à la suite.
• Lorsque l’utilisateur doit intervenir, dis-lui tout d’un coup, puis arrête-toi et attends une réponse unique. Ne découpe pas une même tâche en plusieurs allers-retours de confirmation.
• Montre les commandes d’installation et obtiens l’accord avant de les exécuter — en particulier tout ce qui télécharge et exécute un script depuis le réseau.
• Une fois la configuration MCP ou Skills enregistrée, ne continue pas à sonder la session en cours pour voir si les outils sont apparus. Les nouveaux outils n’arrivent qu’une fois que le client a rechargé — c’est le mécanisme de chargement, pas une panne. L’écriture réussie de la configuration suffit à valider l’étape ; laisse le reste de la vérification pour après le rechargement par l’utilisateur.
• N’exagère jamais l’avancement. Ce qui n’est pas vérifié n’est pas fait. Indique exactement où tu es bloqué et ce que tu as essayé.
• Ne demande jamais à l’utilisateur sa clé API (qui commence par lkai_) ni son jeton d’accès LAN, et n’exécute pas linkly auth set-key à sa place. Ces éléments équivalent à une clé d’accès à sa bibliothèque locale ; tout ce qui passe par une conversation est envoyé au fournisseur du modèle et conservé dans l’historique. Pour te connecter, utilise la connexion en deux étapes linkly auth login (voir R2–R4 dans la branche distante) : l’utilisateur n’a qu’à autoriser dans le navigateur. Si l’utilisateur t’envoie malgré tout une clé ou un jeton, ne l’utilise pas ; dis-lui de la révoquer et d’en créer une nouvelle dans le tableau de bord (https://linkly.ai/dashboard/integrations), ou, pour un jeton LAN, de le régénérer dans « Voir la configuration de connexion MCP » de l’application de bureau.
• Ne contourne pas les exigences de permission, de sécurité ou de vérification. Lorsque la section Dépannage ne couvre pas un problème, exécute d’abord linkly doctor et consulte le guide officiel pertinent ; si tu emploies une approche non mentionnée ici, explique ta raison et revérifie.

​

D’abord, vérifie si tu peux exécuter des commandes

​

Ensuite, vérifie si l’application de bureau a sa place sur cette machine

​

Étape 0 : Diagnostiquer l’état actuel

echo "--- 1. port file ---"
cat ~/.linkly/port 2>/dev/null || echo "NO_PORT_FILE"
echo ""
echo "--- 2. health ---"
PORT=$(sed -n 's/.*"port":\([0-9]*\).*/\1/p' ~/.linkly/port 2>/dev/null)
curl -sf --max-time 5 "http://127.0.0.1:${PORT:-60606}/health" || echo "UNREACHABLE"
echo ""
echo "--- 3. cli ---"
linkly --version 2>/dev/null || echo "NO_CLI"
echo "--- 4. status ---"
linkly status --json 2>/dev/null || echo "NO_STATUS"
echo "--- 5. skills ---"
ls ~/.claude/skills/linkly-ai/SKILL.md ~/.agents/skills/linkly-ai/SKILL.md 2>/dev/null || echo "NO_SKILLS"

Write-Output "--- 1. port file ---"
$port = 60606
if (Test-Path "$HOME\.linkly\port") {
  Get-Content "$HOME\.linkly\port"
  $port = (Get-Content "$HOME\.linkly\port" | ConvertFrom-Json).port
} else { Write-Output "NO_PORT_FILE" }
Write-Output "--- 2. health ---"
try { Invoke-RestMethod "http://127.0.0.1:$port/health" -TimeoutSec 5 | ConvertTo-Json -Compress } catch { "UNREACHABLE" }
Write-Output "--- 3. cli ---"
if (Get-Command linkly -ErrorAction SilentlyContinue) { linkly --version } else { Write-Output "NO_CLI" }
Write-Output "--- 4. status ---"
if (Get-Command linkly -ErrorAction SilentlyContinue) { linkly status --json } else { Write-Output "NO_STATUS" }
Write-Output "--- 5. skills ---"
if ((Test-Path "$HOME\.claude\skills\linkly-ai\SKILL.md") -or (Test-Path "$HOME\.agents\skills\linkly-ai\SKILL.md")) { Write-Output "SKILLS_OK" } else { Write-Output "NO_SKILLS" }

​

Comment interpréter les résultats

{
  "version": "1.1.0",
  "doc_count": 12009,
  "mcp_endpoint": "http://127.0.0.1:60606/mcp",
  "index_status": "watching",
  "capabilities": ["clips-v1", "reveal-v1", "clip-tags-v1"]
}

• Ne code jamais le port 60606 en dur. Ce n’est que la valeur par défaut ; si le port est occupé, l’application l’incrémente. Lis toujours le port réel dans ~/.linkly/port, dont le contenu est un JSON compact : {"port":60606}.
• La présence du fichier de port ne signifie pas que le service tourne. Le fichier subsiste lorsque l’application est tuée de force ou qu’elle plante. Une réponse 200 de /health prouve que le service fonctionne, mais un /health injoignable dans le bac à sable réseau d’un agent IA reste ambigu, car localhost peut y être bloqué.
• Un mcp_endpoint à null signifie que l’interrupteur MCP est désactivé (/health renvoie tout de même 200). Ne te lance pas dans un débogage du port — demande à l’utilisateur de cliquer sur l’icône Agent en bas de la barre latérale gauche de la fenêtre principale pour ouvrir la page « Utilisation par les agents », puis d’activer l’interrupteur « Autoriser l’accès local » dans la zone « Gestion » (ou de cliquer sur le bouton « Démarrer » de la carte « Arrêté »).
• Valeurs de index_status : watching (terminé — le CLI affiche Up to date), scanning, indexing, idle, error.
• doc_count est le nombre de documents indexés — sers-t’en pour évaluer l’avancement de l’indexation, pas comme preuve formelle que les fichiers de l’utilisateur ont bien été pris en compte : ce n’est qu’un total, et 151 contre 150 se distingue à peine lorsqu’un ou deux fichiers seulement ont été ajoutés.

​

Tableau des états

​

Étape 1 : Installer et initialiser

​

1. Télécharger et installer

• macOS : double-cliquez sur le fichier .dmg pour le monter, faites glisser l’icône LinklyAI dans Applications, puis lancez-la depuis le Launchpad.
• Windows : double-cliquez sur le fichier .exe et suivez l’assistant (installation dans le répertoire utilisateur par défaut), puis lancez l’application depuis le menu Démarrer.
• Linux : AppImage x86_64 — chmod +x LinklyAI-*.AppImage && ./LinklyAI-*.AppImage (nécessite glibc 2.35 ou plus récent, ex. Ubuntu 22.04+ / Debian 12+ ; si elle ne démarre pas, suivez le dépannage de l’AppImage Linux).

​

2. Compléter l’assistant du premier lancement

• Écran d’accueil : vous devez cocher « J’ai lu et j’accepte la Politique de confidentialité » pour continuer. Le même écran comporte une option de télémétrie « Aider à améliorer Linkly AI (anonyme) », cochée par défaut, que vous pouvez décocher.
• Apportez vos fichiers (1/2) : « Fichiers d’exemple » est obligatoire ; l’application les indexe en arrière-plan, sans qu’il soit nécessaire d’attendre. Les dossiers « Documents », « Bureau » et « Téléchargements » listés en dessous ne sont pas cochés par défaut et peuvent être cochés au besoin ; sous macOS, cocher l’un d’eux fait apparaître une demande d’autorisation du système, qu’il faut accepter.
• Connecter un agent (2/2) : cliquez sur « Installer » à droite de « Installer la CLI Linkly et les Skills », et l’application installe le CLI et les Skills en arrière-plan ; « Garder la CLI et les Skills à jour » est activé par défaut. Sans clic sur « Installer », rien n’est installé ; l’installation reste possible plus tard depuis la page « Utilisation par les agents » de la fenêtre principale.
• Tout est prêt : cliquez sur « Commencer » pour terminer l’assistant et ouvrir l’accueil de la fenêtre principale.

​

3. Ajouter vos propres dossiers de documents (facultatif)

• Dans la barre latérale gauche de la fenêtre principale, ouvrez « Bibliothèque » et cliquez sur « Ajouter un dossier » pour ajouter les répertoires à indexer (Documents, Téléchargements, un répertoire de projet, etc.) ;
• Ou déposez des fichiers dans le dossier ~/LinklyAI — il est surveillé par défaut, donc tout ce qui y est placé est indexé automatiquement.

​

4. Sache que les modèles se téléchargent en arrière-plan (aucune action requise, mais préviens l’utilisateur)

• La recherche par mots-clés fonctionne immédiatement et n’est absolument pas affectée ;
• La recherche sémantique attend la fin du téléchargement et de l’indexation. D’ici là, search se rabat automatiquement sur la recherche par mots-clés seule (plein texte) — la pertinence baisse légèrement. C’est un comportement attendu, pas un défaut.

​

5. Répondre une seule fois, une fois tout terminé

• Relance d’abord les sondes de l’Étape 0. Ce qui est déjà installé, saute-le (Option A de l’Étape 2 et Étape 3) : ne réinstalle pas.
• Si la commande linkly est introuvable, demande d’abord à l’utilisateur d’ouvrir une nouvelle fenêtre de terminal.
• Exception : si tu es Claude Code et que ~/.claude/skills/linkly-ai n’existe pas, les Skills restent invisibles pour toi (Claude Code ne lit pas ~/.agents/skills). Dans ce cas, exécute quand même linkly skills install, qui crée ce lien.

​

Étape 2 : Connecter le chemin d’accès aux outils

PORT=$(sed -n 's/.*"port":\([0-9]*\).*/\1/p' ~/.linkly/port)
MCP_URL="http://127.0.0.1:$PORT/mcp"

​

Option A : Installer le CLI (recommandé)

curl -sSL https://updater.linkly.ai/cli/install.sh | sh

brew tap LinklyAI/tap
brew install linkly

irm https://updater.linkly.ai/cli/install.ps1 | iex

cargo install linkly-ai-cli

• macOS / Linux : installé dans ~/.linkly/bin/linkly, avec le PATH ajouté dans .zshrc / .bashrc / .profile ;
• Windows : installé dans %LOCALAPPDATA%\linkly\bin\linkly.exe, en modifiant le PATH au niveau de l’utilisateur.

​

Option B : Configurer MCP

• Claude Code : claude mcp add --transport http linkly-ai "$MCP_URL?client=claude-code"
• Codex : codex mcp add linkly-ai --url "$MCP_URL?client=codex"
• Cursor : Settings → MCP Servers → Add Server ; Name linkly-ai, Type StreamableHTTP, l’URL est la valeur résolue de $MCP_URL suivie de ?client=cursor.

1. Démarrer une nouvelle conversation (pour les outils en ligne de commande, quitte et ouvre une nouvelle session). Une conversation déjà en cours conserve la liste d’outils qu’elle avait au démarrage ; une nouvelle récupère la liste à jour.
2. Quitter complètement le client, puis le rouvrir. À utiliser quand la première option ne suffit pas — et attention, fermer la fenêtre n’est pas quitter : sous macOS, appuie sur Cmd + Q ou choisis Quitter dans la barre de menus ; sous Windows, vérifie qu’il a aussi quitté la zone de notification.

curl -sf --max-time 5 -X POST "$MCP_URL" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"setup-probe","version":"1"}}}'

​

Étape 3 : Installer les Skills

npx skills add LinklyAI/linkly-ai-skills

# Claude Code (niveau utilisateur)
git clone https://github.com/LinklyAI/linkly-ai-skills.git ~/.claude/skills/linkly-ai

# Codex CLI
git clone https://github.com/LinklyAI/linkly-ai-skills.git ~/.agents/skills/linkly-ai

https://updater.linkly.ai/skills/linkly-skills-latest.zip

​

Étape 4 : Vérification de bout en bout

linkly search "Holmes" --json

Après avoir rechargé, envoie-moi cette phrase : « recherche Holmes avec linkly-ai ». Si des entrées de documents sont renvoyées, toute la chaîne fonctionne.

​

Branche distante : pas d’application de bureau sur cette machine

​

R1 : Installer le CLI

​

R1.5 : Vérifier une connexion existante

linkly auth status --json

​

R2 : Lancer la connexion

linkly auth login --no-wait --json

​

R3 : Transmettre le lien à l’utilisateur, puis t’arrêter et attendre

• l’url — il peut l’ouvrir sur n’importe quel appareil, téléphone compris ;
• le user_code — il doit vérifier que la page affiche le même code avant de cliquer sur Autoriser ;
• que le lien est valable 10 minutes, et que la page indique quel compte est autorisé, pour qu’il vérifie que c’est le bon.

​

R4 : Terminer la connexion

linkly auth login --wait --json

• Exécute R2 et R4 dans le même environnement, avec le même utilisateur système et le même répertoire de configuration. La connexion en attente y est stockée ; un nouveau conteneur, un autre utilisateur ou un autre LINKLY_CONFIG_DIR ne la voient pas.
• Tu sers plusieurs utilisateurs ? Donne à chacun son propre LINKLY_CONFIG_DIR (un répertoire contient un seul compte) et définis-le sur chaque commande exécutée pour cet utilisateur, par exemple LINKLY_CONFIG_DIR=~/.linkly-alice linkly auth login --no-wait --json.
• Si ton environnement est reconstruit et que les identifiants ont disparu, reconnecte-toi simplement à partir de R2.

​

R5 : Vérifier en trois couches

1. La connexion a réussi : linkly auth status --json affiche "valid": true, avec la formule. Cela prouve seulement le compte ; cela ne prouve pas que du contenu est accessible.
2. La recherche cloud fonctionne (la formule Free suffit) : avec une bibliothèque cloud que l’utilisateur a liée — demande-lui si tu n’en connais aucune —, exécute :
   linkly search "<query>" --remote --library cloud://<owner>/<slug>
   
   Des résultats réels signifient que cela fonctionne. Si l’utilisateur n’a aucune bibliothèque cloud, indique que cette couche a été sautée — pas qu’elle a réussi.
3. La recherche locale fonctionne (les documents sur l’ordinateur de l’utilisateur) : il faut Pro et l’application de bureau en ligne, avec l’Accès distant connecté (voir Accès distant). Vérifie d’abord :
   linkly doctor --remote
   
   Si le tunnel est connecté, exécute linkly search "<query>" --remote et attends des résultats réels. Si l’application de bureau est hors ligne ou si le tunnel n’est pas connecté, signale-le tel quel et demande à l’utilisateur d’ouvrir l’application de bureau, d’activer l’interrupteur « Autoriser l’accès distant (internet) » dans la zone « Gestion » de la page « Utilisation par les agents », puis d’attendre que l’état affiche « Connecté » — n’annonce pas de succès.

​

Dépannage

​

Rends compte une fois terminé

• les étapes que tu as réalisées, et par quelle voie (CLI, MCP ou la branche distante — pour la branche distante, lesquelles des trois couches ont réussi) ;
• si un rechargement est nécessaire pour que quelque chose prenne effet — et si oui, détaille les deux options (« démarrer une nouvelle conversation » / « quitter complètement le client et le rouvrir ») ;
• l’état actuel de l’indexation et le nombre de documents ;
• comment l’utiliser concrètement — par exemple en ajoutant use linkly-ai à la fin de n’importe quel prompt, ou en appuyant sur Cmd/Ctrl + L pour ouvrir le lanceur de recherche et sur Cmd/Ctrl + K pour ouvrir la fenêtre principale (les utilisateurs venant d’une ancienne version conservent les raccourcis qu’ils avaient définis).

​

Termine par quatre exemples de questions

1. Lisez A Life in 10 Years et analysez les schémas de vie récurrents dans les dix années de journal de Samuel Pepys — ainsi que les angles morts qu’il n’a peut-être jamais vus lui-même.
2. Qu’est-ce qui fait vraiment gagner Sherlock Holmes ? Lisez les 12 affaires de Detectives Library, dégagez sa formule de résolution, puis transformez la méthode de Holmes en checklist pour diagnostiquer des problèmes business complexes.
3. De quoi les fondateurs de l’Amérique avaient-ils vraiment peur ? Lisez l’intégralité des Federalist Papers et donnez-moi une réponse. Expliquez comment ils ont conçu un système où l’ambition contrebalance l’ambition et où les factions s’équilibrent — puis traduisez cette logique en principes de gouvernance pour les entreprises d’IA ou les plateformes internet d’aujourd’hui.
4. Après avoir lu les souvenirs racontés par des centaines d’anciens esclaves, qu’est-ce que les manuels d’histoire américains osent le moins détailler ? Répondez à partir des WPA Slave Narratives.

​

Pour aller plus loin

• Démarrage rapide — le guide complet d’installation et de prise en main, rédigé pour les humains
• Utiliser le CLI — toutes les sous-commandes et tous les paramètres du CLI
• Utiliser MCP — les trois modes d’accès et la configuration par client
• Utiliser les Skills — comment les Skills s’installent et comment ils fonctionnent