Solución de problemas

El agente no arranca

Síntoma: el contenedor se detiene inmediatamente o entra en bucle de reinicios.

Comprueba los logs:

docker compose logs nubulus-tunnel

Causas más comunes:

Error en los logs	Causa	Solución
`TUNNEL_TOKEN is required`	Falta la variable de entorno	Añade `TUNNEL_TOKEN` al `docker-compose.yml`
`API error: status 401`	Token incorrecto o expirado	Genera un nuevo token en el panel
`API error: status 403`	El túnel está suspendido o eliminado	Verifica el estado en el panel
`no se pudo iniciar WireGuard`	Error de conectividad	Verifica acceso saliente UDP al puerto 51820

El túnel arranca pero no llegan peticiones

Síntoma: el agente muestra túnel conectado pero las peticiones al dominio no llegan.

Comprueba:

Que el dominio tiene un CNAME apuntando a la dirección que indica el panel de Nubulus.
Que las rutas están configuradas en el panel y tienen el hostname correcto.
Que el agente recibe tráfico (verifica rx en los logs de estadísticas):

docker compose logs nubulus-tunnel | grep "transfer stats"

Si rx es 0 después de varios minutos, el tráfico no está llegando al túnel. Revisa la configuración DNS de tu dominio.

Respuesta 502 Bad Gateway

Síntoma: el navegador muestra un error 502.

Comprueba los logs del agente en busca de:

"upstream connection failed"

Si aparece ese error, el agente sí recibe la petición pero no puede alcanzar tu servicio. Causas habituales:

El servicio no está en la misma red Docker que el agente. Añade ambos a la misma red en docker-compose.yml.
El nombre del upstream no coincide. El nombre en la ruta del panel debe ser exactamente el nombre del servicio en Docker Compose (sensible a mayúsculas y guiones).
El puerto es incorrecto. Verifica en qué puerto escucha tu servicio.

Si aparece "no matching route" en cambio, el hostname que envía el navegador no coincide con el configurado en las rutas del panel:

"no matching route" host="lo-que-llega" path="/"

Verifica que el hostname en la ruta del panel coincide exactamente con el dominio que estás usando.

Las rutas no se actualizan

Síntoma: cambias las rutas en el panel pero el agente sigue usando las anteriores.

El agente comprueba cambios cada 30 segundos por defecto. Espera un momento y vuelve a intentarlo.

Si tras un minuto siguen sin aplicarse, revisa los logs:

docker compose logs -f nubulus-tunnel | grep "poll\|rutas"

Si ves errores de conexión en el poll, puede haber un problema de acceso a la API de Nubulus desde tu servidor.

Cómo leer los logs

Los logs del agente son JSON estructurado (clave ts para timestamp, level, msg). Puedes filtrarlos con jq:

# Solo errores y warnings
docker compose logs nubulus-tunnel | jq 'select(.level == "ERROR" or .level == "WARN")'

# Ver el estado actual del túnel
docker compose logs nubulus-tunnel | jq 'select(.msg == "agent.state")'

# Ver estadísticas de transferencia
docker compose logs nubulus-tunnel | jq 'select(.msg == "transfer stats")'

Para activar logs más detallados temporalmente:

docker compose stop nubulus-tunnel
LOG_LEVEL=debug docker compose up nubulus-tunnel

Generar un bundle de diagnóstico

Si necesitas compartir información con soporte, el agente incluye el subcomando diagnose que genera un archivo .tar.gz con un snapshot completo del estado, redactando automáticamente cualquier secreto (tokens, claves, contraseñas):

docker compose exec nubulus-tunnel tunnel-agent diagnose

El comando imprime la ruta del bundle en stdout. Puedes capturarla directamente:

BUNDLE=$(docker compose exec nubulus-tunnel tunnel-agent diagnose 2>/dev/null)
docker compose cp nubulus-tunnel:$BUNDLE ./diagnostico.tar.gz

El bundle incluye:

Estado del agente y métricas en el momento del diagnóstico
Información del sistema operativo y del runtime de Go
Sondas de red al endpoint WireGuard (ping, TCP, UDP, MTU, rutas locales)
Variables de entorno con secretos redactados
Un manifest.json con la lista de redacciones aplicadas

Para ejecutar solo las comprobaciones de sistema (sin pruebas de red, más rápido):

docker compose exec nubulus-tunnel tunnel-agent diagnose --no-network

Estado del agente en tiempo real

El agente expone un endpoint de estado en 127.0.0.1:9999/status que puedes consultar desde el host:

# Desde el host (si expones el puerto en docker-compose)
curl http://127.0.0.1:9999/status | jq .state

# Desde dentro del contenedor
docker compose exec nubulus-tunnel wget -qO- http://127.0.0.1:9999/status | jq .state

Los estados posibles son:

Estado	Descripción
`initializing`	El agente está arrancando
`connected`	Túnel activo y con handshake reciente
`degraded`	El túnel sigue activo pero se detecta pérdida de paquetes o latencia alta
`reconnecting`	El agente está intentando restablecer la conexión
`stopping`	El agente está cerrando de forma ordenada
`failed`	Error irrecuperable; el contenedor se reiniciará