Modo Daemon

Por defecto Hive corre como un servidor stdio por sesión: tu cliente MCP lanza uvx hive-vault en cada sesión y lo cierra al terminarla. Es el modo más simple y no necesita nada de esta página.

El modo daemon es una mejora opcional. En lugar de un servidor por sesión, un único proceso hive serve de larga vida es el dueño del vault, y cada sesión se conecta a través de un shim ligero hive client que hace de proxy. Merece la pena activarlo cuando ejecutas varias sesiones concurrentes en una máquina, quieres las garantías de único dueño de ADR-011, o quieres que los clientes adopten siempre la última versión publicada de forma automática.

Solo equipos de un usuario hasta resolver #456

El endpoint estable sirve TLS con un certificado por usuario que todos los clientes de Hive fijan, así que un listener que suplante el puerto estable durante una caída falla el handshake antes de recibir ningún bearer. No despliegues el modo daemon en equipos multiusuario no confiables hasta resolver #456: aún se está registrando la evidencia en Linux y Windows, incluida la comprobación entre usuarios. Si falta el daemon, hive client falla explícitamente; nunca inicia otro servidor in-process.

Los dos procesos

Comando	Rol
hive serve	El daemon. Sirve MCP sobre streamable-HTTP en loopback con TLS 1.3 y un certificado por usuario, protegido con bearer token. Único dueño del git + SQLite del vault por máquina (garantizado por un lock singleton).
hive client	Un shim stdio ligero que lanza tu cliente MCP. Hace de proxy hacia un hive serve en marcha; falla explícitamente si no hay ninguno alcanzable.
hive service	Instala/elimina el supervisor del SO que mantiene hive serve en marcha. Ver abajo.

En modo daemon tu cliente MCP se registra con hive client en lugar de uvx hive-vault — el proceso cliente es barato de lanzar y no añade latencia de carga del vault al inicio de sesión.

Activarlo

hive service integra hive serve en el supervisor de tu SO para que arranque al iniciar sesión y se reinicie ante fallos. Es multiplataforma: systemd --user en Linux, Task Scheduler en Windows, launchd en macOS.

uv tool install --upgrade hive-vault   # requiere hive-vault >= 1.32.0
hive service install                   # renderiza unit/task, habilita, arranca
hive service status                    # vista del supervisor + sondeo /health anclado

• Linux escribe ~/.config/systemd/user/hive.service (Restart=on-failure, WantedBy=default.target), y luego ejecuta systemctl --user daemon-reload && enable --now.
• Windows registra la tarea programada HiveVaultDaemon (LogonTrigger + RestartOnFailure).
• macOS escribe ~/Library/LaunchAgents/io.github.mlorentedev.hive.plist (RunAtLoad, KeepAlive {SuccessfulExit: false}) y lo carga en el dominio gui/<uid> con launchctl bootstrap. Ese dominio solo existe para un usuario con sesión iniciada en la consola: ejecútalo desde un terminal del Mac, no desde una sesión solo SSH. La salida va a ~/Library/Logs/hive/serve.log.

Usa hive service install --no-enable para escribir el unit/task sin arrancarlo, y hive service uninstall para detenerlo y eliminarlo.

hive service status termina con hive daemon: healthy (código 0) solo cuando quien escucha en el puerto estable demuestra el certificado del daemon. Si no, informa unverified listener (posible suplantación), unverified listener, owner unknown o down, y sale con 1. Si el daemon se niega a arrancar porque sus ficheros de identidad están dañados o no son solo del propietario, detenlo y ejecuta hive service rotate-identity, que sustituye la clave, el certificado y el token.

El último paso es apuntar tu cliente MCP al daemon — cambia la entrada hive de uvx hive-vault a hive client. El procedimiento completo por máquina (verificar que el daemon sirve, la edición quirúrgica de ~/.claude.json, y el rollback) está en el runbook de Activación del Daemon.

Para GitHub Copilot CLI en un equipo confiable de un solo usuario, registra copilot mcp add hive -- hive client a nivel de usuario. Si cambias el puerto, define HIVE_DAEMON_PORT tanto para el daemon como para el cliente. Deshabilita la entrada antigua hive-vault después de comprobar la nueva; evita registrar dos dueños del vault. El smoke automatizado de tests/test_daemon.py inicializa en menos de 4,1 segundos, lista herramientas y llama a vault_health contra el daemon real por stdio y HTTPS directo; no ejecuta la CLI de Copilot. Copilot documenta MCP timeout para descubrimiento y llamadas de herramientas, incluido el presupuesto de conexión. En el equipo Windows medido, el inicio en frío terminó tras ~4,1 segundos pese a timeout: 30000; es una observación, no un plazo universal documentado.

El registro recomendado es hive client. Un registro directo solo está soportado como https://127.0.0.1:<puerto>/mcp, con el host verificando el certificado del daemon: en hosts basados en Node, como Copilot CLI, define NODE_EXTRA_CA_CERTS=<directorio de estado>/daemon.crt en el entorno de ese host. Nunca desactives la verificación (NODE_TLS_REJECT_UNAUTHORIZED=0 o un flag “insecure”); un host que no pueda verificar usa hive client. Los registros http:// ya no funcionan, porque el daemon solo habla TLS. El HTTPS directo solo cuenta como soportado en una plataforma cuando un host MCP concreto ha pasado allí la comprobación con host real; hasta entonces, usa hive client. No pongas el bearer en archivos de configuración ni en el historial de shell.

Auto-actualización: reinicio-al-actualizar

Una vez supervisado, el daemon se mantiene al día. Sondea su propia versión instalada y, cuando hay un hive-vault más nuevo en disco, sale con código 75 (EX_TEMPFAIL) para que la política Restart=on-failure del supervisor lo relance con el nuevo código. Sin reinicio manual, y sin añadir latencia al arranque del cliente.

Linux / macOS: uv tool upgrade hive-vault
Windows:       hive self-upgrade [version]
        │
        ▼
hive serve detecta el drift       # dentro de HIVE_UPGRADE_POLL_S
        │
        ▼
exit 75  ──►  el supervisor reinicia  ──►  el daemon corre la nueva versión

Así, el mecanismo de actualización vive en el paquete; cada cuánto actualizas es una política de despliegue que tú controlas. Linux y macOS pueden usar un uv tool upgrade hive-vault periódico (por ejemplo, un timer de systemd --user). En Windows, usa hive self-upgrade de forma deliberada; crea un runtime versionado y cambia la junction activa de forma atómica en lugar de reemplazar archivos que podrían estar en uso. El daemon adopta la versión instalada en su siguiente sondeo.

Una parada por señal (graceful) o una instalación rechazada salen con 0, que bajo Restart=on-failure no dispara un relanzamiento — solo el camino de drift devuelve el código de reinicio distinto de cero. Las escrituras en vuelo son seguras ante un reinicio porque son idempotentes at-most-once (ADR-013).

Ajustar el intervalo de sondeo

Variable	Por defecto	Descripción
HIVE_UPGRADE_POLL_S	30.0	Segundos entre comprobaciones de drift de versión en hive serve. Menor = el daemon adopta una versión nueva antes tras una actualización; mayor = menos búsquedas importlib.metadata. Validado > 0 y <= 3600.

Defínela en el entorno del daemon (en Linux, vía Environment= / EnvironmentFile= del unit; en macOS, ~/.config/hive/hive.env, que el agente carga al arrancar; en Windows, el entorno del perfil de usuario que hereda la tarea programada).

Verificar el daemon

El daemon escribe su puerto, el bearer token, la clave TLS y el certificado en el directorio de estado de Hive (solo-dueño, 600). Solo sirve TLS 1.3; confía en su propio certificado, nunca en el almacén del sistema ni en -k:

STATE=~/.local/share/hive
PORT=$(cat "$STATE/daemon.port")
CERT="$STATE/daemon.crt"

curl -s --cacert "$CERT" "https://127.0.0.1:$PORT/health"                     # {"status":"ok","ready":true,...}
curl -s --cacert "$CERT" -o /dev/null -w '%{http_code}\n' "https://127.0.0.1:$PORT/status"  # 401 (token-gated)
curl -s --cacert "$CERT" -H "Authorization: Bearer $(cat "$STATE/daemon.token")" \
  "https://127.0.0.1:$PORT/status"                                            # 200 + métricas

En el primer arranque tras actualizar desde un daemon en claro, el token se rota una vez, porque antes viajó sin cifrar. hive client toma el token nuevo en su siguiente arranque; los registros directos hay que actualizarlos.

/status expone sessions_started, total_calls y la versión en marcha — útil para confirmar que un reinicio-al-actualizar adoptó de verdad el nuevo código.

Cuándo quedarse en stdio

El modo daemon es opt-in. Quédate en uvx hive-vault si ejecutas una sola sesión a la vez, no quieres procesos de fondo, o estás en una plataforma sin supervisor soportado — el servidor por sesión es completo y usa el mismo código de vault y workers. Puedes cambiar más tarde en cualquier momento sin migración de datos: hive client falla explícitamente sin el daemon en vez de iniciar silenciosamente otro dueño del vault.