Guía de instalación para Agentes

Completa la configuración con https://linkly.ai/docs/es/agent-setup.md

​

Para el agente de IA

​

Tu tarea

1. La aplicación de escritorio Linkly AI esté instalada, inicializada e indexando: con los ejemplos incluidos basta; los documentos propios del usuario son un extra; y
2. Tú —u otra herramienta de IA que el usuario posea— puedas invocar realmente las herramientas de recuperación de Linkly AI y encontrar un documento real.

​

Tus límites y reglas

• Puedes hacer tú mismo: ejecutar comandos de sondeo, instalar la CLI, configurar MCP, instalar Skills, ejecutar comandos de verificación, interpretar errores e informar de los resultados. Para cualquier cosa que instale software, muestra el comando y obtén consentimiento primero.
• El usuario debe hacer: descargar y ejecutar el instalador, completar el asistente de configuración, añadir carpetas de documentos en la aplicación y conceder permisos del sistema. Son acciones de interfaz gráfica: tú no puedes hacerlas.

• Sondea antes de actuar. Puede que el usuario ya tenga parte de la configuración hecha, o que esté reinstalando: no recorras a ciegas todos los pasos desde el principio.
• Verifica cada paso. Cada paso indica su criterio de aceptación. Si la comprobación no pasa, no avances.
• Cuando el usuario deba actuar, dilo todo de una vez, luego detente y espera una única respuesta. No dividas una misma tarea en varias rondas de confirmación de ida y vuelta.
• Muestra los comandos de instalación y obtén consentimiento antes de ejecutarlos, especialmente cualquier cosa que descargue y ejecute un script desde la red.
• Una vez escrita la configuración de MCP o de Skills, no sigas sondeando la sesión actual para ver si han aparecido las herramientas. Las herramientas nuevas solo llegan cuando el cliente recarga: es el mecanismo de carga, no un fallo. Escribir la configuración correctamente ya completa el paso; deja el resto de la verificación para después de que el usuario recargue.
• Nunca exageres el progreso. Si no está verificado, no está hecho. Di exactamente dónde te has atascado y qué has intentado.
• No pidas al usuario su API Key (la que empieza por lkai_) ni su token de acceso LAN, y no ejecutes linkly auth set-key por él. Equivalen a la llave de su biblioteca local; todo lo que pasa por una conversación se envía al proveedor del modelo y queda guardado en el historial. Para iniciar sesión, usa el flujo de dos pasos de linkly auth login (ver R2–R4 en la rama remota): el usuario solo autoriza en el navegador. Si el usuario te envía igualmente una clave o un token, no lo uses; dile que lo revoque y cree uno nuevo en el panel (https://linkly.ai/dashboard/integrations) o, si es un token LAN, que lo regenere en «Ver la configuración de conexión MCP» de la aplicación de escritorio.
• No eludas los requisitos de permisos, seguridad o verificación. Cuando la sección Resolución de problemas no cubra un problema, ejecuta primero linkly doctor y consulta la guía oficial correspondiente; si usas un enfoque no listado aquí, explica tu motivo y vuelve a verificar.

​

Primero, comprueba si puedes ejecutar comandos

​

Después, comprueba si la aplicación de escritorio va en esta máquina

​

Paso 0: Sondear el estado actual

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" }

​

Cómo interpretar los resultados

{
  "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"]
}

• Nunca codifiques de forma fija el puerto 60606. Es solo el valor por defecto; si el puerto está ocupado, la aplicación va incrementándolo. Lee siempre el puerto real de ~/.linkly/port, cuyo contenido es JSON compacto: {"port":60606}.
• Que exista el archivo de puerto no significa que el servicio esté en ejecución. El archivo queda atrás cuando la aplicación se cierra a la fuerza o se bloquea. Un 200 de /health demuestra que el servicio está sano, pero un /health inalcanzable dentro del sandbox de red de un agente de IA no es concluyente, porque el sandbox puede bloquear localhost.
• Que mcp_endpoint sea null significa que el interruptor de MCP está desactivado (/health sigue devolviendo 200). No te pongas a depurar el puerto: pide al usuario que haga clic en el icono de agente en la parte inferior de la barra lateral izquierda de la ventana principal para abrir la página «Uso por agentes» y active el interruptor «Permitir acceso local» de la sección «Gestión» (o pulse el botón «Iniciar» de la tarjeta «Detenido»).
• Valores de index_status: watching (terminado — la CLI muestra Up to date), scanning, indexing, idle, error.
• doc_count es el número de documentos indexados: úsalo para calibrar el progreso de la indexación, no como prueba concluyente de que los archivos del usuario se han recogido: es solo un total, y 151 frente a 150 apenas se distingue cuando solo se añadió uno o dos archivos.

​

Tabla de estados

​

Paso 1: Instalar e inicializar

​

1. Descargar e instalar

• macOS: haz doble clic en el .dmg para montarlo, arrastra el icono de LinklyAI a Applications y luego inícialo desde Launchpad.
• Windows: haz doble clic en el .exe y sigue el asistente (se instala en el directorio del usuario por defecto), luego inícialo desde el menú Inicio.
• Linux: AppImage x86_64 — chmod +x LinklyAI-*.AppImage && ./LinklyAI-*.AppImage (requiere glibc 2.35 o superior, p. ej., Ubuntu 22.04+ / Debian 12+; si no arranca, sigue la guía de resolución de problemas de la AppImage para Linux).

​

2. Completar el asistente del primer inicio

• Portada: Debes marcar «He leído y acepto la Política de Privacidad» para continuar. En la misma pantalla hay una opción de telemetría, «Ayuda a mejorar Linkly AI (anónimo)», marcada por defecto, que puedes desmarcar.
• Trae tus archivos (1/2): «Archivos de ejemplo» es obligatorio; la aplicación los indexa en segundo plano, sin necesidad de esperar. Debajo, «Documentos», «Escritorio» y «Descargas» vienen sin marcar y se pueden marcar según convenga; en macOS, al marcarlos aparece un cuadro de autorización del sistema en el que hay que pulsar Permitir.
• Conectar un agente (2/2): pulsa «Instalar» a la derecha de «Instalar la CLI de Linkly y las Skills» y la aplicación instalará la CLI y las Skills en segundo plano; «Mantener la CLI y las Skills actualizadas» está activado por defecto. Si no se pulsa «Instalar», no se instala nada; también se puede instalar más adelante desde la página «Uso por agentes» de la ventana principal.
• Todo listo: pulsa «Empezar» para cerrar el asistente y abrir la página de inicio de la ventana principal.

​

3. Añade tus propias carpetas de documentos (opcional)

• Abre «Biblioteca» en la barra lateral izquierda de la ventana principal, pulsa «Añadir carpeta» y añade los directorios a indexar (Documentos, Descargas, un directorio de proyecto, etc.);
• O deja archivos en la carpeta ~/LinklyAI: está vigilada por defecto, así que todo lo que se coloque ahí se indexa automáticamente.

​

4. Ten en cuenta que los modelos se descargan en segundo plano (no requiere acción, pero avisa al usuario)

• La búsqueda por palabras clave funciona de inmediato y no se ve afectada en absoluto;
• La búsqueda semántica espera a que terminen la descarga y la indexación. Hasta entonces, search recurre automáticamente a la recuperación solo por palabras clave (texto completo): la relevancia baja ligeramente. Es el comportamiento esperado, no un fallo.

​

5. Responde una sola vez cuando todo esté hecho

• Vuelve a ejecutar los sondeos del Paso 0. Si ya están instaladas, sáltate la Opción A del Paso 2 y el Paso 3; no las instales de nuevo.
• Si no se encuentra el comando linkly, pide primero al usuario que abra una nueva ventana de terminal.
• Excepción: si eres Claude Code y ~/.claude/skills/linkly-ai no existe, las Skills siguen sin ser visibles para ti (Claude Code no lee ~/.agents/skills). En ese caso ejecuta igualmente linkly skills install, que crea ese enlace.

​

Paso 2: Conectar la vía de acceso a las herramientas

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

​

Opción A: Instalar la CLI (recomendado)

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: se instala en ~/.linkly/bin/linkly, con el PATH añadido a .zshrc / .bashrc / .profile;
• Windows: se instala en %LOCALAPPDATA%\linkly\bin\linkly.exe, modificando el PATH a nivel de usuario.

​

Opción B: Configurar 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, la URL es el valor resuelto de $MCP_URL con ?client=cursor al final.

1. Iniciar una conversación nueva (en herramientas de línea de comandos, sal y abre una sesión nueva). Una conversación que ya está en marcha conserva la lista de herramientas con la que arrancó; una nueva recoge la más reciente.
2. Salir del cliente por completo y volver a abrirlo. Úsalo cuando la primera opción no sirva; y ten en cuenta que cerrar la ventana no es salir: en macOS pulsa Cmd + Q o elige Salir en la barra de menús, y en Windows comprueba que también haya salido de la bandeja del sistema.

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"}}}'

​

Paso 3: Instalar Skills

npx skills add LinklyAI/linkly-ai-skills

# Claude Code (user level)
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

​

Paso 4: Verificación de extremo a extremo

linkly search "Holmes" --json

Tras recargar, mándame esta frase: «busca Holmes con linkly-ai». Si devuelve entradas de documentos, toda la cadena funciona.

​

Rama remota: sin aplicación de escritorio en esta máquina

​

R1: Instalar la CLI

​

R1.5: Comprobar si ya hay sesión iniciada

linkly auth status --json

​

R2: Iniciar el inicio de sesión

linkly auth login --no-wait --json

​

R3: Pasar el enlace al usuario, y detenerte a esperar

• la url: puede abrirla en cualquier dispositivo, también en el móvil;
• el user_code: debe comprobar que la página muestra el mismo código antes de hacer clic en Autorizar;
• que el enlace es válido durante 10 minutos y que la página muestra qué cuenta se está autorizando, para que confirme que es la correcta.

​

R4: Completar el inicio de sesión

linkly auth login --wait --json

• Ejecuta R2 y R4 en el mismo entorno, con el mismo usuario del sistema y el mismo directorio de configuración. El inicio de sesión pendiente se guarda allí; un contenedor nuevo, otro usuario u otro LINKLY_CONFIG_DIR no lo ven.
• ¿Atiendes a varios usuarios? Dale a cada uno su propio LINKLY_CONFIG_DIR (un directorio contiene una sola cuenta) y defínelo en cada comando que ejecutes para ese usuario, p. ej. LINKLY_CONFIG_DIR=~/.linkly-alice linkly auth login --no-wait --json.
• Si tu entorno se reconstruye y las credenciales desaparecen, simplemente vuelve a iniciar sesión desde R2.

​

R5: Verificar en tres capas

1. El inicio de sesión funcionó: linkly auth status --json muestra "valid": true, junto con el plan. Esto solo demuestra la cuenta; no demuestra que haya contenido accesible.
2. La búsqueda en la nube funciona (basta el plan Free): con una biblioteca en la nube que el usuario haya vinculado —pregúntale si no conoces ninguna—, ejecuta:
   linkly search "<query>" --remote --library cloud://<owner>/<slug>
   
   Si devuelve resultados reales, funciona. Si el usuario no tiene ninguna biblioteca en la nube, di que esta capa se ha omitido, no que ha pasado.
3. La búsqueda local funciona (los documentos del escritorio del usuario): requiere Pro y que la aplicación de escritorio esté en línea con el Acceso remoto conectado (ver Acceso remoto). Comprueba primero:
   linkly doctor --remote
   
   Si el túnel está conectado, ejecuta linkly search "<query>" --remote y espera resultados reales. Si la aplicación de escritorio está desconectada o el túnel no está conectado, informa exactamente de eso y pide al usuario que abra la aplicación de escritorio, active el interruptor «Permitir acceso remoto (internet)» en la sección «Gestión» de la página «Uso por agentes» y espere a que el estado muestre «Conectado»; no declares éxito.

​

Resolución de problemas

​

Informa cuando hayas terminado

• qué pasos completaste y por qué vía (CLI, MCP o la rama remota; en la rama remota, cuáles de las tres capas pasaron);
• si es necesaria una recarga para que algo surta efecto y, en tal caso, detalla las dos opciones («iniciar una conversación nueva» / «salir del cliente por completo y volver a abrirlo»);
• el estado actual de la indexación y el número de documentos;
• cómo usarlo realmente — por ejemplo, añadiendo use linkly-ai a cualquier prompt, o pulsando Cmd/Ctrl + L para abrir el lanzador de búsqueda y Cmd/Ctrl + K para abrir la ventana principal (quien haya actualizado desde una versión anterior conserva los atajos que tenía configurados).

​

Termina con cuatro preguntas de ejemplo

1. Lee A Life in 10 Years y analiza los patrones de vida recurrentes en los diez años de diarios de Samuel Pepys, y los puntos ciegos que quizá él mismo nunca llegó a ver.
2. ¿En qué gana realmente Sherlock Holmes? Lee los 12 casos de Detectives Library, extrae su fórmula para resolver casos y convierte el método de Holmes en una checklist para diagnosticar problemas de negocio complejos.
3. ¿Qué temían realmente los fundadores de Estados Unidos? Lee los Federalist Papers completos y dame una respuesta. Explica cómo diseñaron un sistema donde la ambición frena a la ambición y las facciones se equilibran, y luego traduce esa lógica en principios de gobernanza para las empresas de IA o las plataformas de internet de hoy.
4. Tras leer los recuerdos contados en primera persona por cientos de personas antes esclavizadas, ¿qué es lo que los libros de historia de Estados Unidos menos se atreven a contar en detalle? Responde basándote en las WPA Slave Narratives.

​

Lecturas adicionales

• Inicio rápido — la guía completa de instalación e incorporación, escrita para personas
• Usar CLI — todos los subcomandos y parámetros de la CLI
• Usar MCP — los tres modos de acceso y la configuración por cliente
• Usar Skills — cómo se instalan Skills y cómo funcionan