Instalación

zqagent tiene dos formas de instalación: herramienta de línea de comandos (CLI) y app de escritorio. Esta página explica la instalación, actualización y desinstalación de la CLI.

¿No quieres usar la línea de comandos? Consulta la app de escritorio: descarga el instalador y usa la interfaz gráfica.

Lo más rápido: instalación en una línea (Linux / macOS)

curl -fsSL https://agent.cd-zq.com/install.sh | sh
# En un servidor, ejecútalo como root para instalarlo como servicio de inicio automático
curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh

El script lee el manifiesto oficial, descarga el ejecutable único de tu arquitectura, verifica el SHA-256 y lo instala en el PATH; no hace falta instalar Node antes. Por defecto se instala en /usr/local/bin (si hay permisos de escritura) o en ~/.local/bin. Admite Linux (x64 / arm64) y macOS (Intel x64 / Apple Silicon arm64).

Tras instalar, se registra como servicio de inicio automático (systemd en Linux / launchd en macOS; se reinicia si falla) y muestra el estado actual y tres formas de uso:

Uso	Cómo
Interfaz gráfica	Abre http://127.0.0.1:8787 en el navegador
Línea de comandos	zqagent (escribe /connect para configurar el modelo)
Gestión remota	Conectar con la cuenta del Hub: zqagent link --hub https://hub.cd-zq.com --username <correo/teléfono> --password '<contraseña>' (también con código)

En máquinas con terminal, al final de la instalación se pregunta si conectar al Hub: introduce el correo/teléfono y la contraseña registrados en el Hub, sin mostrar la contraseña. En automatizaciones puedes pasar la cuenta en el comando (mejor la contraseña por variable de entorno):

# Introducir la contraseña oculta (sin eco y sin quedar en el historial)
read -rsp 'Contraseña del Hub: ' ZQAGENT_HUB_PASSWORD; echo
curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh -s -- \
  --username you@example.com --password "$ZQAGENT_HUB_PASSWORD"

# O con un código de conexión de un solo uso (válido 15 minutos)
curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh -s -- --code <código>

Si no quieres conectar durante la instalación, añade --no-enroll y ejecuta zqagent link después.

Si se ejecuta sin root o el contenedor no tiene systemd, se omite el servicio y se indica el comando para arrancar en primer plano; si solo quieres la CLI, añade --no-service.

Se puede ejecutar repetidamente: si ya está instalado y actualizado, no vuelve a descargar y solo informa del estado (versión, servicio activo, accesibilidad de la dirección local, conexión al Hub, canal de actualización); si hay versión nueva, actualiza y reinicia el servicio.

Argumentos habituales (se pasan con sh -s --):

# Cambiar puerto / dirección de escucha / directorio de datos
curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh -s -- --port 9000 --host 0.0.0.0

# Instalar en un directorio propio
curl -fsSL https://agent.cd-zq.com/install.sh | sh -s -- --bin-dir ~/bin

# Solo la CLI, sin servicio de inicio automático
curl -fsSL https://agent.cd-zq.com/install.sh | sh -s -- --no-service

# Conectar con la cuenta del Hub tras instalar (o --code <código>)
read -rsp 'Contraseña del Hub: ' ZQAGENT_HUB_PASSWORD; echo
curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh -s -- \
  --username you@example.com --password "$ZQAGENT_HUB_PASSWORD"

# Omitir la pregunta de conexión del final
curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh -s -- --no-enroll

# Forzar la descarga y sobrescritura aunque ya esté instalado
curl -fsSL https://agent.cd-zq.com/install.sh | sh -s -- --force

# Forzar el uso de npm
curl -fsSL https://agent.cd-zq.com/install.sh | sh -s -- --npm

# No enviar estadísticas anónimas de instalación
curl -fsSL https://agent.cd-zq.com/install.sh | sh -s -- --no-telemetry

El script de una línea es para macOS / Linux. En Windows descarga el exe de archivo único (no necesita Node en la máquina de destino) o instala con npm como se explica abajo.

Sobre las estadísticas de instalación: tras una instalación correcta se envía un registro anónimo a nuestro servicio de estadísticas (solo versión, plataforma, arquitectura y método de instalación), para conocer el uso real por plataforma. No incluye nombre de usuario, ruta de instalación, IP ni información identificable, y no usa cookies. Si no lo quieres, añade --no-telemetry o define ZQAGENT_NO_TELEMETRY=1 para desactivarlo por completo.

Notas sobre macOS

• Arquitectura del chip: Intel (macos-x64) y Apple Silicon (macos-arm64) descargan su propio artefacto.
• Inicio automático: instalado como root se registra como LaunchDaemon (/Library/LaunchDaemons/com.zqagent.node.plist, arranca al iniciar el sistema); como usuario normal se registra como LaunchAgent (~/Library/LaunchAgents/, arranca al iniciar sesión). El plist incluye KeepAlive, así que launchd relanza el proceso si termina.
• Actualización automática: igual que en Linux: el servicio descarga en silencio y verifica la firma con el manifiesto; cuando está inactivo reemplaza el binario y sale, y launchd arranca la nueva versión. zqagent update --status muestra el estado gestionado y la última comprobación.
• Desinstalación: sudo sh -s -- uninstall. Limpia el Daemon del sistema y el Agent del usuario que ejecutó sudo; el directorio de datos y el binario se conservan, y repetirlo no da error.
• Instancia única: al reinstalar como root se elimina antes el LaunchAgent de ese usuario, evitando que dos instancias (sistema y usuario) se disputen el mismo puerto.

Directorio de datos por defecto: usuario normal ~/Library/Application Support/zqagent; instalado como root /var/root/Library/Application Support/zqagent.

Los artefactos de archivo único de las dos arquitecturas de macOS se publican con cada versión y no requieren Node previo. Si en algún manifiesto falta el artefacto de la arquitectura actual, el script recurre a npm (requiere Node ≥ 18.17); si el directorio global de npm no es escribible, instala en ~/.local y lo indica.

Cambio automático de puerto si está ocupado

El puerto por defecto 8787 suele estar ocupado por otro servicio en máquinas de desarrollo. El script comprueba el puerto antes de registrar el servicio y, si está ocupado, prueba 8788, 8789… imprimiendo cada intento, y genera la configuración con el puerto final:

→ Comprobando si el puerto 8787 está libre ...
! El puerto 8787 está ocupado por otro proceso
→ Probando el puerto 8788 ...
! Se cambió automáticamente al puerto 8788 (el 8787 previsto estaba ocupado)
  Consola local: http://127.0.0.1:8788

El proceso del nodo tiene la misma protección: si al arrancar el puerto sigue ocupado, cambia al siguiente libre y lo explica en el registro; el puerto real se escribe en el archivo server-port del directorio de datos, y tanto el script como zqagent update --status informan la dirección a partir de él.

Si el puerto lo ocupa este mismo nodo (servicio ya en marcha), el script lo reutiliza y no arranca una segunda instancia. Para fijarlo usa --port <puerto>; si los 20 puertos consecutivos desde el inicial están ocupados, termina con error.

Archivo único de Windows (sin Node)

El artefacto de Windows es un único zqagent.exe; la máquina de destino no necesita Node/npm.

Requisitos: Windows 10 / Server 2016 o superior (solo 64 bits x64 o ARM64). Windows 7, 8, 8.1 y Server 2008 R2 / 2012 no pueden ejecutarlo: faltan API del sistema y instalar el runtime de C++ no lo resuelve. Consulta Versiones compatibles de Windows.

1. Descarga el artefacto de tu arquitectura (sin Node/npm en destino):

   Arquitectura	Para	Descarga
   x64	Casi todos los Windows	zqagent-windows-x64

   El nombre incluye versión y fecha de compilación; el enlace apunta automáticamente a la versión publicada al compilar el sitio. El manifiesto completo está en https://agent.cd-zq.com/downloads/zqagent/stable.json (binaries.windows-x64.url). Actualmente no hay artefacto para Windows ARM64; usa la versión x64 (Windows la ejecutará emulada).

2. Colócalo en cualquier directorio (por ejemplo %LOCALAPPDATA%\zqagent\) y ejecútalo en PowerShell o cmd:

   .\zqagent-windows-x64-v<versión>-<fecha>.exe

   Tras el primer arranque, escribe /connect para configurar el modelo.

3. Si quieres escribir zqagent directamente: añade ese directorio al PATH del usuario («Propiedades del sistema → Variables de entorno») y renombra el archivo a zqagent.exe. Por línea de comandos (setx trunca PATH demasiado largos):

   setx PATH "%PATH%;%LOCALAPPDATA%\zqagent"

Dejarlo como nodo con gestión remota:

zqagent.exe serve --port 8787 --data-dir "%APPDATA%\zqagent"

Si necesitas inicio automático, crea en el «Programador de tareas» una tarea «Al iniciar sesión»: en programa pon la ruta absoluta del exe y en argumentos serve --port 8787 --data-dir "%APPDATA%\zqagent".

• Windows no tiene systemd / launchd, así que el archivo único no habilita la actualización automática (tras reemplazarse no hay gestor de servicios que lo relance). Para actualizar: detén el proceso → descarga el nuevo exe y sobrescribe → vuelve a iniciar.
• El artefacto no tiene firma Authenticode (inyectar SEA rompe la firma de node.exe); la primera ejecución puede mostrar un aviso de SmartScreen. Antes de distribuirlo oficialmente, fírmalo de nuevo con signtool.
• La CLI ya incluye ripgrep, no hace falta instalar rg aparte.

Requisitos del sistema

Elemento	Requisito
Sistema operativo	macOS / Linux / Windows. Windows requiere 10 / Server 2016 o superior (la app de escritorio, 10 1709+); consulta Versiones compatibles de Windows
Node.js	≥ 18.17 (solo para la instalación por npm; los archivos únicos de Linux / macOS / Windows incluyen el runtime)
Red	Acceso a agent.cd-zq.com (archivo único) o al npm público registry.npmjs.org (npm)

Subcomandos: gestionar el nodo instalado

install.sh también es una herramienta de gestión. Además de instalar, admite los subcomandos status / logs / restart / rollback / print-config (añade sudo si hace falta):

sudo sh -s -- status        # versión, servicio, dirección local, acceso remoto, actualización automática
sudo sh -s -- logs          # seguir los registros del nodo
sudo sh -s -- restart       # reiniciar el servicio
sudo sh -s -- rollback      # volver a la versión anterior a la última actualización automática
sudo sh -s -- print-config  # solo imprime la configuración que se usaría, sin ejecutar nada
sudo sh -s -- uninstall     # desinstalar el servicio (conserva datos y binario)

Al ejecutarlo por tubería, el subcomando va después de sh -s --:

curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh -s -- status

Si ya descargaste el script, pásalo como argumento: sudo sh install.sh status.

El script de instalación:

1. Lee la última versión del manifiesto oficial y descarga el binario de tu plataforma/arquitectura
2. Verifica el SHA-256 y la versión
3. Obtiene automáticamente la clave pública de verificación (o se indica con --pubkey)
4. Instala en /usr/local/bin/zqagent (o ~/.local/bin)
5. Lo registra como servicio: systemd en Linux, launchd en macOS

Así que basta un comando, sin buscar la clave pública a mano.

Instalación con configuración (puerto, directorio de datos)

curl -fsSLO https://agent.cd-zq.com/install.sh
sudo sh install.sh --port 8787 --data-dir /srv/zqagent

Indicar la clave pública uno mismo (opcional)

Si no se pasa --pubkey, el script la obtiene de $BASE_URL/update-public.b64. Ese archivo comparte origen con el manifiesto de actualización, así que esta confianza por defecto depende de que «el HTTPS y el dominio del sitio no estén comprometidos». Para una garantía mayor, guarda una copia de la clave pública fuera de banda y pásala explícitamente al instalar:

sudo sh install.sh --pubkey "$(cat /path/to/update-public.b64)"

La clave indicada tiene prioridad y el script no la sobrescribe por red; si el formato no es válido, termina con error.

Argumento	Descripción	Valor por defecto
--port <n>	Puerto de escucha	8787
--host <addr>	Dirección de escucha	127.0.0.1
--data-dir <dir>	Directorio de datos	Linux ~/.zqagent_data; macOS ~/Library/Application Support/zqagent (los registros lo siguen)
--pubkey <key>	Clave pública de verificación de actualizaciones	Se obtiene de $BASE_URL/update-public.b64
--service-name <n>	Nombre de la unit de systemd	zqagent
--label <name>	Nombre del job de launchd	com.zqagent.node
--channel <name>	Canal de actualización	stable
--version <x.y.z>	Versión concreta	La última del manifiesto
--no-service	Solo instalar el binario	—

En Windows usa la app de escritorio; dentro de WSL puedes instalar como en Linux.

Instalación en un servidor remoto

No hace falta entrar antes al servidor: puedes lanzar la instalación desde tu máquina por SSH. Basta con que el servidor tenga curl y sudo; no necesita Node/npm, porque se descarga un binario único con runtime incluido.

ssh deploy@your-server \
  'curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh'

Si necesitas puerto o directorio de datos propios, descarga primero y ejecuta después (por tubería no se pueden pasar argumentos):

ssh deploy@your-server '
  curl -fsSLO https://agent.cd-zq.com/install.sh &&
  sudo sh install.sh --port 8787 --data-dir /srv/zqagent
'

Tras instalar, los subcomandos son los mismos install.sh status|logs|restart|rollback, y las actualizaciones posteriores las hace el nodo automáticamente según el manifiesto (ver la sección siguiente).

La dirección antigua install-node.sh (/downloads/zqagent/install-node.sh) publicada antes de la unificación sigue recibiendo una copia con el mismo contenido; los scripts existentes no necesitan cambios, pero se recomienda usar install.sh en los nuevos.

Actualización de la instalación por archivo único

El nodo instalado con archivo único se actualiza solo: descarga la nueva versión en silencio y, cuando no hay tareas en ejecución, se reemplaza y reinicia. Consulta Iniciar el nodo · Actualización automática.

Para comprobarlo a mano:

zqagent update --check     # ¿hay versión nueva?
zqagent update --status    # versión actual, canal, última comprobación

Origen del software

Los paquetes de la serie @zqagent se publican en npm público (https://registry.npmjs.org/); no hace falta registrarse ni solicitar cuenta, y se instalan con el origen por defecto de npm.

Si tu npm usa un mirror nacional (registry.npmmirror.com, etc.), también funciona: el mirror se sincroniza automáticamente tras publicar. En ambos casos no hay que configurar un scope aparte para @zqagent.

Instalación por npm (desarrolladores / ya usas Node)

Adecuada si quieres tener zqagent siempre a mano en la máquina de desarrollo; queda fuera de la actualización automática y se actualiza con npm.

# Usar el origen por defecto del equipo (recomendado)
npm i -g @zqagent/core

# O indicar temporalmente el npm público
npm i -g @zqagent/core --registry=https://registry.npmjs.org/

Canales de versión

Actualmente el npm público solo publica la versión estable (etiqueta latest):

Canal	Comando	Descripción
Estable (predeterminado)	npm i -g @zqagent/core@latest	Actualiza latest en cada publicación; apto para uso diario

Sin versión equivale a @latest. El canal de pruebas @dev que mencionaba documentación antigua aún no está abierto; npm i -g @zqagent/core@dev dará error de versión no encontrada, no lo uses.

Verificar la instalación

zqagent link --help       # macOS / Linux (ya en el PATH)

.\zqagent-windows-x64-v<versión>-<fecha>.exe link --help    :: archivo único de Windows (sin PATH)

Después ejecuta zqagent para entrar en la CLI interactiva y /connect para configurar el modelo; consulta Inicio rápido.

Actualización y desinstalación

Archivo único de Windows

:: Actualizar: detén el serve en ejecución y sobrescribe el archivo con el nuevo exe
:: (el nombre no cambia, así que no hay que tocar el Programador de tareas ni los accesos directos)
copy /Y zqagent-windows-x64.exe "%LOCALAPPDATA%\zqagent\zqagent.exe"

:: Desinstalar: detén el proceso y elimina el exe y el directorio de datos
rmdir /S /Q "%LOCALAPPDATA%\zqagent"

Instalación por archivo único (install.sh, macOS / Linux)

# Actualizar: vuelve a ejecutar el script; si ya es la última, solo informa
curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh

# Desinstalar el servicio (conserva datos y binario)
curl -fsSL https://agent.cd-zq.com/install.sh | sudo sh -s -- uninstall

# Limpieza total (Linux; los datos están por defecto en el home del usuario que ejecuta)
sudo rm -rf ~/.zqagent_data /usr/local/bin/zqagent

# Limpieza total (macOS; en instalación de usuario los datos están en ~/Library/Application Support/zqagent)
sudo rm -rf "/var/root/Library/Application Support/zqagent" /usr/local/bin/zqagent

Instalar y desinstalar se pueden repetir: si ya está instalado no se vuelve a descargar y solo se informa del estado; ejecutar uninstall sin servicio tampoco da error. Reinstalar tras desinstalar reutiliza el binario y el directorio de datos conservados, y las credenciales del Hub y la configuración de modelos siguen ahí.

Instalación por npm

# Actualizar a la última estable
npm i -g @zqagent/core@latest

# Desinstalar
npm uninstall -g @zqagent/core

Actualizar solo reemplaza el programa y no toca tu configuración de modelos ni los datos de conversaciones (la configuración está en ~/.config/zqagent/ y los datos de sesiones y proyectos en sus directorios; ver Iniciar el nodo).

Preguntas frecuentes

¿Aparece zqagent: command not found? El directorio bin global no está en el PATH. Compruébalo y añádelo:

Con el archivo único de Windows, ejecútalo con la ruta completa o .\zqagent.exe; para añadirlo al PATH, consulta Archivo único de Windows.

npm prefix -g        # muestra el prefijo global de npm; bin está dentro (en Windows, el mismo directorio)
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc   # macOS/Linux

¿Error de permisos EACCES al instalar? El directorio global de npm pertenece a root. No uses sudo npm i -g; usa un gestor de versiones (nvm/fnm) o cambia el prefijo global de npm a tu directorio de usuario:

npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc

¿La instalación va lenta o caduca? Comprueba que puedes acceder a https://registry.npmjs.org/ (o al mirror configurado); en redes corporativas puedes configurar un proxy HTTP:

npm config set proxy http://<host>:<port>
npm config set https-proxy http://<host>:<port>

¿Hay que reconfigurar en otra máquina?~/.npmrc y ~/.config/zqagent/ están en el directorio del usuario, así que al cambiar de máquina hay que reconfigurar el origen; la API Key del modelo se puede reconectar con /connect.

Siguiente paso

• Inicio rápido: conectar el modelo y completar la primera tarea
• Iniciar el nodo: dejar zqagent como nodo con gestión remota
• Consola del nodo: gestionar nodos, conversaciones y uso con interfaz gráfica