mage-hands
Relés MCP efímeros y privilegiados para administrar equipos de laboratorio en casa (NAS Synology, routers) a través de Tailscale. Proporciona autenticación por token, auditoría forense y ejecución de comandos raíz controlada mediante un sistema de 'leases' gestionado fuera de banda.
Ficha actualizada 25 sept 2026, 20:04 · upstream 25 sept 2026, 19:45 · release sin release detectada
Qué es mage-hands
Descripción editorial construida a partir del repositorio, su documentación y sus señales de mantenimiento.
Mage-hands es una arquitectura de dos capas diseñada para permitir que Claude Code administre dispositivos remotos sin ejecutar agentes directamente en ellos. La capa Core (`mage_hands_core`) provee el framework reutilizable con autenticación, auditoría forense y políticas de seguridad centralizadas. La capa Appliances implementa servidores delgados específicos para cada dispositivo objetivo, como `synology-hands` para NAS Synology DSM 7.2+.
El sistema opera mediante relés siempre activos que ejecutan solicitudes estructuradas localmente en el host objetivo. La seguridad se basa en aislamiento de red (vinculación a loopback y acceso exclusivo vía Tailscale), tokens Bearer, un gate de 'lease' para acciones mutantes y una política de auditoría forense JSONL. Las herramientas están divididas en tres niveles: inspección (Tier A), lectura de archivos controlada (Tier A gated) y ejecución raíz con patrones de denegación (Tier C).
El despliegue requiere un entorno Docker en el equipo objetivo, Tailscale configurado con MagicDNS y HTTPS, y una estación Mac con Claude Code. La gestión de cambios críticos se realiza mediante un comando `nas-unlock` que valida la identidad del operador fuera de banda, evitando la exposición directa a internet.
- Administración remota segura de NAS Synology (DSM) sin ejecutar agentes completos en el dispositivo.
- Auditoría forense continua de estado del sistema, uso de disco y salud del almacenamiento mediante Tier A.
- Gestión controlada de reglas de firewall y reinicio de servicios o contenedores con validación de lease.
- Inspección de exposición a internet y diagnóstico de red en el laboratorio doméstico.
- Ejecución de comandos raíz limitados para mantenimiento (ej. `smartctl`, actualizaciones) con replay tokens únicos.
- Aislamiento de red estricto: el relay se vincula solo a loopback y es accesible exclusivamente a través de Tailscale.
- Sistema de 'lease' (alquiler) para acciones mutantes que requiere validación fuera de banda con YubiKey.
- Auditoría forense JSONL integrada en la capa Core para rastrear identidad y acciones del operador.
- Compatibilidad verificada con Synology DSM 7.2+ utilizando `nsenter` para ejecutar herramientas nativas sin montar socket Docker.
- Autenticación de transporte robusta mediante StaticTokenVerifier que devuelve 401 si el token es inválido.
- El relay opera con privilegios root en el host objetivo y no está sandboxeado; la seguridad depende del aislamiento de red.
- La gestión de 'leases' para cambios críticos requiere una interacción manual fuera de banda (ej. `nas-unlock`).
- Requiere que el equipo objetivo tenga Docker o un gestor de contenedores compatible con la arquitectura.
- Dependencia obligatoria de Tailscale y MagicDNS configurado correctamente en ambos extremos.
- La capa Core no incluye sandboxing nativo; la seguridad depende de las políticas de acceso a archivos y comandos.
Perfil de infraestructura
Estimación inicial derivada del repositorio y de los servicios detectados.
Despliegue detectado
Qué señales reales de instalación hemos encontrado.
Despliegue en NAS Synology DSM 7.2+ con Docker. Requiere Tailscale instalado en el NAS y la Mac del usuario, habilitando MagicDNS y HTTPS en la red Tailnet. El relay se ejecuta en un contenedor privilegiado (pid:host) que accede al host vía nsenter. Se recomienda configurar las políticas de acceso a archivos y revisar ARCHITECTURE.md para entender los niveles de herramientas antes de habilitar Tier B o C.
Stack y dependencias
Componentes inferidos a partir de manifests, configuración y documentación.
Puede sustituir a
Relaciones detectadas por el análisis del repositorio y su categoría.
Experiencia real de la comunidad
Ayuda a contrastar la estimación automática con instalaciones reales.
Todavía no hay datos comunitarios para este proyecto.