Si quieres decidir dónde se guardan los datos de las sesiones y cómo se configura el relay, puedes ejecutar tu propio relay. El relay en la nube funciona bien, pero con el autoalojamiento todo queda en tus manos.

Esta guía explica cómo ejecutar un relay privado de Happier.

En resumen

Docker (el punto de partida recomendado):

docker pull happierdev/relay-server:stable
docker run -d \
  -p 3600:3600 \
  -e HANDY_MASTER_SECRET="$(openssl rand -hex 32)" \
  -e NODE_ENV=production \
  --name happier-relay \
  happierdev/relay-server:stable

O instalación gestionada:

happier relay host install --mode system

Después, configura los clientes para que usen la URL de tu relay en lugar de la predeterminada.

El problema

Usar el relay en la nube implica que:

• Los datos de las sesiones pasan por una infraestructura que no controlas
• No controlas dónde se guardan los datos ni las políticas de retención
• Dependes de la disponibilidad del servicio en la nube
• Puedes personalizar poco los límites de uso y las políticas

Para algunos flujos de trabajo, no pasa nada. Para otros, quieres:

• Ser dueño de toda la infraestructura
• Que los datos se queden en tu red o en el hosting que elijas
• Autenticación y políticas de acceso propias
• Controlar las actualizaciones y la configuración

Enfoques habituales y sus concesiones

• Relay en la nube: funciona bien, pero tus datos no están en tu propia infraestructura.
• Compilar desde el código fuente: es posible, pero tienes que estar al día con las dependencias y los pasos de compilación.
• Implementar un relay propio: supondría una carga de mantenimiento.

Autoalojar el relay oficial lo resuelve:

• Imágenes de Docker ya compiladas
• Opción de instalación gestionada
• El mismo protocolo de relay que la versión en la nube
• Control total del despliegue

Si Happier es nuevo para ti

Happier es una app complementaria de código abierto para agentes de programación con IA como Claude Code, Codex y OpenCode.

El relay es el componente de servidor que:

• Encamina los mensajes entre tus dispositivos
• Guarda los metadatos de las sesiones
• Gestiona la autenticación
• Ofrece paso de mensajes con cifrado de extremo a extremo

Si autoalojas el relay, tus sesiones y aprobaciones nunca salen de tu infraestructura.

Para empezar:

• GitHub: https://github.com/happier-dev/happier
• Documentación de autoalojamiento: https://docs.happier.dev/self-hosting
• Discord: https://discord.gg/W6Pb8KuHfg

Requisitos previos

Elige un método de despliegue:

Para Docker (recomendado)

• Docker instalado
• Un host con IP pública o acceso por red privada
• El puerto 3600 libre (o configura otro puerto)

Para la instalación gestionada

• Una máquina Linux o macOS
• La CLI de Happier instalada
• Posibilidad de ejecutar servicios (systemd o servicios de usuario)

Para el runner (avanzado)

• Node.js o Bun
• Un gestor de procesos (PM2, systemd, etc.)
• Gestión manual de artefactos

Opción 1: Docker (recomendado para la mayoría)

Con Docker empiezas a autoalojar enseguida y con poca configuración.

1) Descarga la imagen

docker pull happierdev/relay-server:stable

Etiquetas disponibles:

• stable: versiones de producción
• preview: versiones preliminares
• dev: compilaciones de desarrollo

En producción, quédate con stable.

2) Genera un secreto maestro

El secreto maestro cifra los datos en reposo y sirve para derivar los tokens de autenticación.

openssl rand -hex 32

Guarda este valor en un lugar seguro. No lo pierdas: si cambias el secreto, los datos existentes dejan de poder leerse.

3) Ejecuta el contenedor

docker run -d \
  -p 3600:3600 \
  -e HANDY_MASTER_SECRET="your-secret-from-step-2" \
  -e NODE_ENV=production \
  --name happier-relay \
  --restart unless-stopped \
  happierdev/relay-server:stable

4) Comprueba que está en marcha

docker logs happier-relay

Deberías ver:

[info] Happier relay server starting...
[info] Listening on http://0.0.0.0:3600

5) Configura los clientes para que usen tu relay

Desde la app de Happier:

1. Ve a Configuración (Settings) → Servidor (Server)
2. Añade un nuevo perfil de servidor
3. Introduce la URL de tu relay: http://your-server-ip:3600
4. Guarda y conéctate

Desde la CLI de Happier:

happier config set relay.url http://your-server-ip:3600

Consulta la guía rápida de autoalojamiento para configurar los clientes en detalle.

Opción 2: instalación gestionada (despliegue como servicio)

La instalación gestionada crea un servicio del sistema que arranca al iniciar la máquina e incluye comandos de actualización.

1) Instala la CLI de Happier

Sigue la guía de instalación de la CLI.

2) Instala el relay como servicio del sistema

happier relay host install --mode system

Para instalarlo en modo usuario (sin sudo):

happier relay host install --mode user

3) Configura el secreto maestro

Edita la configuración del servicio:

sudo nano /etc/happier-relay/env

Añade:

HANDY_MASTER_SECRET=your-secret-here
NODE_ENV=production

4) Inicia el relay

happier relay host start

5) Comprueba el estado

happier relay host status

Deberías ver:

Relay service: active (running)

6) Configura los clientes

Igual que con Docker: añade la URL de tu relay a la configuración de los clientes.

Opción 3: runner (para usuarios avanzados)

El runner descarga y verifica los artefactos del relay al arrancar y luego ejecuta el binario del servidor.

Es para configuraciones en las que:

• Ya tienes un gestor de procesos
• Quieres que los artefactos se descarguen al reiniciar
• No quieres Docker ni gestión de servicios

1) Ejecuta el paquete del servidor relay

npx --yes --package @happier-dev/relay-server happier-server \
  --master-secret "your-secret-here" \
  --port 3600

2) Úsalo con un gestor de procesos

Ejemplo con PM2:

pm2 start npx --name happier-relay -- \
  --yes --package @happier-dev/relay-server happier-server \
  --master-secret "your-secret-here" \
  --port 3600
pm2 save

Consulta la documentación del runtime de autoalojamiento para más detalles sobre el runner.

Configuración del entorno

Variables de entorno principales:

Consulta la documentación de variables de entorno para ver la lista completa.

Configuración de la autenticación

Por defecto, el relay usa autenticación con contraseña.

En producción, plantéate:

• GitHub OAuth: consulta autenticación con GitHub
• OIDC: consulta autenticación OIDC
• mTLS: consulta autenticación mTLS

HTTPS y proxy inverso

En producción, pon el relay detrás de un proxy inverso con HTTPS.

Ejemplo con nginx:

server {
    listen 443 ssl;
    server_name relay.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:3600;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Después, los clientes se conectan a: https://relay.example.com

Actualizaciones

Docker

docker pull happierdev/relay-server:stable
docker stop happier-relay
docker rm happier-relay
# Re-run the docker run command with the new image

Instalación gestionada

happier relay host install --mode system
happier relay host restart

Runner

El runner descarga automáticamente los artefactos nuevos al reiniciar.

Solución de problemas

Síntoma: el contenedor se cierra nada más arrancar

Causa probable:

• Falta HANDY_MASTER_SECRET o no es válido
• El puerto ya está en uso

Solución:

1. Revisa los logs del contenedor: docker logs happier-relay
2. Comprueba que las variables de entorno están definidas
3. Comprueba si el puerto está libre: lsof -i :3600

Síntoma: los clientes no se pueden conectar

Causa probable:

• El cortafuegos bloquea el puerto 3600
• El relay no escucha en la interfaz correcta
• El cliente tiene una URL de relay equivocada

Solución:

1. Comprueba que el relay está en marcha: docker ps o happier relay host status
2. Revisa el cortafuegos: sudo ufw allow 3600/tcp
3. Prueba la conexión: curl http://your-server-ip:3600
4. Comprueba que la URL del relay en el cliente coincide con la dirección del servidor

Síntoma: errores de "Authentication failed"

Causa probable:

• El secreto maestro cambió entre el relay y el registro del cliente
• El relay se reinició sin conservar los tokens de autenticación

Solución:

1. Comprueba que HANDY_MASTER_SECRET es el mismo
2. Vuelve a registrar los clientes si cambió el secreto maestro
3. Revisa los logs del relay en busca de errores de autenticación

Síntoma: las actualizaciones no se aplican

Docker:

• Asegúrate de descargar la imagen antes de volver a crear el contenedor
• Comprueba que la etiqueta de la imagen no ha cambiado

Instalación gestionada:

• Vuelve a ejecutar happier relay host install
• Reinicia el servicio después de la instalación

Preguntas frecuentes

¿Necesito autoalojarlo?

No. El relay en la nube funciona bien para la mayoría de usuarios.

Autoalójalo cuando:

• Necesites garantías sobre dónde se guardan los datos
• Quieras controlar toda la infraestructura
• Tengas requisitos de cumplimiento normativo
• Prefieras servicios gestionados por ti

¿Puedo pasar de la nube a un relay autoalojado?

Sí, pero las sesiones no se migran automáticamente.

Pasos:

1. Monta el relay autoalojado
2. Configura los clientes para que usen la nueva URL del relay
3. Las sesiones existentes siguen en el relay en la nube
4. Las sesiones nuevas usan el relay autoalojado

¿Sigue activo el cifrado de extremo a extremo?

Sí. El cifrado E2E se hace en el cliente, sea cual sea el relay que uses.

Quien opere el relay (tú o el proveedor en la nube) no puede leer el contenido de las sesiones en ningún caso.

¿Cómo hago copia de seguridad de los datos del relay?

El relay guarda los datos en su directorio de datos.

Docker: Añade un volumen:

-v /path/to/data:/data

Instalación gestionada: La ubicación de los datos depende del sistema operativo. Compruébala con: happier relay host status

Copia de seguridad:

1. Detén el relay
2. Copia el directorio de datos
3. Vuelve a iniciar el relay

¿Puedo ejecutar varias instancias del relay?

Sí, para alta disponibilidad o balanceo de carga.

Requisitos:

• Un almacén de datos compartido (base de datos)
• Un balanceador de carga delante
• El mismo HANDY_MASTER_SECRET en todas las instancias

Consulta la documentación del entorno para configurar un clúster.

Guías relacionadas

• Cómo usar Happier desde el móvil
• Happier frente a Claude Code Remote Control