Quieres llegar desde internet a un servicio que corre en tu casa. No tienes IP fija, no piensas abrir un puerto en el router y tampoco te apetece que todo tu tráfico pase por Cloudflare. Pangolin resuelve exactamente ese caso: un servidor pequeño en un VPS recibe las peticiones, las autentica y las manda por un túnel que tu red abrió hacia fuera. Esta guía instala Pangolin con Docker Compose, da de alta el conector Newt y publica un primer servicio.

Puntos clave

  • El conector Newt sale de tu red hacia el VPS por WebSocket y WireGuard, de modo que en casa no hay ningún puerto escuchando ni hace falta IP fija.
  • La versión estable en el momento de escribir esto es Pangolin 1.22.0, publicada el 27 de agosto de 2026, con Newt 1.16.0 del 19 de agosto.
  • El despliegue son tres contenedores: el servidor de Pangolin, Gerbil para los túneles de WireGuard y Traefik v3.7 como entrada, con el complemento Badger haciendo de autenticación.
  • Los certificados los pide Traefik a Let’s Encrypt por desafío HTTP, así que necesitas los puertos 80 y 443 abiertos en el VPS, más 51820 y 21820 en UDP.
  • Ganas control y pierdes comodidad: el VPS pasa a formar parte de tu perímetro de seguridad, y su ancho de banda y su tiempo de servicio son ahora tuyos.

Qué es Pangolin y por dónde sale la conexión

Pangolin es un proxy inverso con túnel y control de identidad, publicado por Fossorial bajo licencia dual AGPL-3 y licencia comercial propia. El repositorio fosrl/pangolin[1] se abrió en septiembre de 2024 y a finales de agosto de 2026 acumula 22.550 estrellas y 769 bifurcaciones. Está escrito en TypeScript; el conector va en Go y sí es AGPL-3 puro.

La pieza que cambia la ecuación es la dirección de la conexión. En un montaje clásico de proxy inverso, tú abres un puerto en el router y esperas a que el mundo llame. Aquí ocurre al revés: el conector Newt, instalado en tu red, abre dos conexiones salientes hacia el servidor.

Una es un WebSocket contra el plano de control, por donde recibe la configuración. La otra es un túnel de WireGuard[2] contra Gerbil, por donde viajan los datos.

Diagrama del recorrido de una petición pública en Pangolin: Internet, Traefik, Badger, Gerbil, el conector Newt y finalmente el servicio alojado en tu propia red.

Cada nodo de Pangolin ejecuta tres procesos con nombre propio. Traefik termina el TLS y enruta. Badger es un complemento de Traefik que aplica la autenticación antes de dejar pasar nada. Gerbil mantiene los pares de WireGuard y hace de repetidor cuando la perforación de NAT falla.

Si ya tienes Traefik montado con Docker Compose, reconocerás casi todo el fichero de configuración.

Una garantía que conviene tener clara desde el principio: instalar un conector no expone nada. La documentación lo dice así: "Sites are software-defined proxies and deny traffic by default". Hasta que no defines un recurso y le das acceso a alguien, ese túnel no lleva a ninguna parte.

Qué necesitas antes de instalar Pangolin

Cuatro cosas, y ninguna es opcional.

Un servidor Linux con IP pública. El proyecto pide como mínimo 1 vCPU, 2 GB de memoria y 8 GB de disco, y recomienda 2 vCPU con 20 GB para uso normal. Por debajo de 1 GB de memoria vas a necesitar espacio de intercambio para que la instalación no se atragante.

Un dominio propio, con acceso a su zona de DNS. Necesitas un registro A comodín apuntando al VPS, porque cada servicio que publiques será un subdominio distinto:

Tipo: A     Nombre: *     Valor: IP_DE_TU_VPS     TTL: 300
Tipo: A     Nombre: @     Valor: IP_DE_TU_VPS     TTL: 300

Cuatro puertos abiertos en el cortafuegos del VPS: 80 y 443 en TCP, 51820 en UDP para los túneles de los sitios y 21820 en UDP para los clientes. Ese último solo hace falta si vas a usar recursos privados con el cliente de escritorio.

Y una dirección de correo real, que es la que Let’s Encrypt asocia a tus certificados y la que usarás para la primera cuenta de administrador.

Cómo desplegar Pangolin en el VPS con Docker Compose

Existe un instalador automático (curl -fsSL https://static.pangolin.net/get-installer.sh | bash) que hace preguntas y escribe los ficheros por ti. Aquí vamos por el camino manual, que es el mismo resultado con la ventaja de que entiendes qué has puesto. Son cuatro pasos:

  1. Crea el árbol de directorios del proyecto.
  2. Escribe los tres ficheros de configuración con tu dominio.
  3. Levanta la pila y espera a que los contenedores queden sanos.
  4. Abre la página de alta inicial con el testigo que Pangolin imprime en su registro.

El árbol es fijo y conviene respetarlo, porque los montajes del compose dependen de él:

mkdir -p config/db config/letsencrypt config/traefik/logs

El fichero docker-compose.yml levanta las tres piezas. Fíjate en que Traefik no publica puertos: comparte la pila de red de Gerbil, que es quien los expone. Esa línea network_mode: service:gerbil es la que más gente borra por parecer rara, y sin ella el TLS deja de funcionar:

name: pangolin
services:
  pangolin:
    image: docker.io/fosrl/pangolin:latest
    container_name: pangolin
    restart: unless-stopped
    volumes:
      - ./config:/app/config
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3001/api/v1/"]
      interval: "10s"
      timeout: "10s"
      retries: 15

  gerbil:
    image: docker.io/fosrl/gerbil:latest
    container_name: gerbil
    restart: unless-stopped
    depends_on:
      pangolin:
        condition: service_healthy
    command:
      - --reachableAt=http://gerbil:3004
      - --generateAndSaveKeyTo=/var/config/key
      - --remoteConfig=http://pangolin:3001/api/v1/
    volumes:
      - ./config/:/var/config
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
    ports:
      - 51820:51820/udp
      - 21820:21820/udp
      - 443:443
      - 80:80

  traefik:
    image: docker.io/traefik:v3.7
    container_name: traefik
    restart: unless-stopped
    network_mode: service:gerbil
    depends_on:
      pangolin:
        condition: service_healthy
    command:
      - --configFile=/etc/traefik/traefik_config.yml
    volumes:
      - ./config/traefik:/etc/traefik:ro
      - ./config/letsencrypt:/letsencrypt
      - ./config/traefik/logs:/var/log/traefik

networks:
  default:
    driver: bridge
    name: pangolin

Con los ficheros escritos, el arranque es una orden y una comprobación:

sudo docker compose up -d
sudo docker compose ps
sudo docker compose logs pangolin | grep -i token

En el primer arranque Pangolin crea config/db/db.sqlite, Gerbil escribe su clave en config/key y el servidor imprime por consola un testigo de alta de un solo uso. Con ese testigo entras en https://pangolin.tudominio.com/auth/initial-setup y creas la cuenta de administrador. Si el navegador se queja del certificado durante el primer minuto, es normal: Let’s Encrypt todavía está validando.

Qué valores hay que tocar en config.yml

El fichero de la aplicación es corto y todo lo que trae de ejemplo hay que sustituirlo. Estos son los valores que no puedes dejar como vienen:

gerbil:
    start_port: 51820
    base_endpoint: "pangolin.tudominio.com"

app:
    dashboard_url: "https://pangolin.tudominio.com"
    log_level: "info"

domains:
    domain1:
        base_domain: "tudominio.com"

server:
    secret: "genera-uno-con-openssl-rand-hex-32"
    cors:
        origins: ["https://pangolin.tudominio.com"]

flags:
    require_email_verification: false
    disable_signup_without_invite: true
    allow_raw_resources: true

El secreto del servidor se genera con openssl rand -hex 32 y no se reutiliza de ningún otro sitio. Si algún día hay que rotarlo, la herramienta interna pangctl rotate-server-secret lo hace sin tocar la base de datos a mano.

Hay dos ajustes de red que se deciden ahora o nunca. Gerbil reparte direcciones dentro de 100.89.137.0/20, un rango de la zona CGNAT elegido para no chocar con las redes privadas habituales, y asigna una /30 a cada sitio, es decir cuatro direcciones. Si ese rango se solapa con tu red, cámbialo antes de registrar el primer Gerbil; después ya no.

En el fichero de Traefik hay dos sustituciones más. Una es tu correo en el resolvedor letsencrypt, que usa desafío HTTP contra el punto de entrada web. La otra es la versión del complemento Badger, fijada en v1.4.0 en la plantilla oficial.

Cómo instalar Newt en la máquina de tu red

Primero se crea el sitio en el panel, y el panel te devuelve tres datos: un identificador, un secreto y el punto de conexión. Con eso, la instalación del conector en la máquina de casa es directa:

curl -fsSL https://static.pangolin.net/get-newt.sh | bash

newt 
  --id 31frd0uzbjvp721 
  --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 
  --endpoint https://pangolin.tudominio.com

Eso vale para probar. Para dejarlo funcionando, el proyecto documenta un servicio de systemd que lee las credenciales de /etc/newt/newt.env con permisos 600. Así el secreto no acaba en la lista de procesos ni en el historial del intérprete de órdenes.

Si prefieres contenedor, la imagen es fosrl/newt y las tres variables son PANGOLIN_ENDPOINT, NEWT_ID y NEWT_SECRET. La documentación propone además una variante más limpia: meter la configuración en un fichero JSON y pasarlo como secreto de Compose con CONFIG_FILE=/run/secrets/newt-config.

services:
  newt:
    image: fosrl/newt
    container_name: newt
    restart: unless-stopped
    environment:
      - PANGOLIN_ENDPOINT=https://pangolin.tudominio.com
      - NEWT_ID=2ix2t8xk22ubpfy
      - NEWT_SECRET=nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2

Hay otros dos tipos de sitio y conviene saber que existen para descartarlos. El sitio local expone servicios que viven en el propio VPS, sin túnel. El sitio de WireGuard básico usa una conexión cruda sin canal de control, exige NAT para alcanzar otras máquinas de la red. Renuncia a los recursos privados, a las comprobaciones de estado y al descubrimiento del socket de Docker.

Newt es el camino recomendado y el único con el juego completo.

Exponer el primer servicio de principio a fin

Un recurso público de tipo HTTP es lo que la mayoría busca. Le asignas un nombre completo dentro del dominio que registraste. Añades uno o más destinos con su dirección y su puerto en la red remota, y eliges el sitio por el que se llega. Pangolin termina el TLS, aplica las reglas de acceso y solo entonces mete la petición en el túnel.

Con más de un destino en sitios distintos obtienes reparto de carga por turnos y relevo automático cuando una comprobación de estado falla. Con uno solo tienes lo que necesitas para publicar tu servidor de notas o tu panel de métricas.

El certificado no requiere ninguna acción por tu parte: al crear el recurso, Traefik pide el certificado a Let’s Encrypt contra el subdominio nuevo y lo guarda en config/letsencrypt/acme.json. Ese es el motivo por el que el puerto 80 tiene que seguir abierto aunque no sirvas nada sin cifrar.

Qué autenticación trae de serie

Todos los recursos públicos nacen con la sesión única de Pangolin activada. A partir de ahí las opciones se acumulan y se pueden compartir mediante políticas entre los recursos que elijas:

Método Para qué sirve
Sesión única de Pangolin Usuario, contraseña y segundo factor dentro del propio panel
Proveedor de identidad externo Google, Azure Entra ID, Okta o cualquier OIDC genérico
Usuarios y roles Acceso por persona o por grupo, recurso a recurso
PIN o contraseña de acceso Barrera simple para algo que no merece una cuenta
Cabecera de autorización Peticiones de máquina a máquina con usuario y contraseña
Código temporal por correo Lista blanca por dominio, del estilo *@tuempresa.com
Enlaces compartibles Acceso puntual con caducidad, revocable borrando el enlace
Reglas ordenadas Permitir o denegar por IP, por país o por ruta

La lista blanca por dominio de correo es la que resuelve el caso doméstico más habitual: dar acceso a la familia sin crear cuentas. Los enlaces compartibles llevan un testigo que viaja como parámetro p_token o en las cabeceras P-Access-Token-Id y P-Access-Token, y hay que enviarlo en cada petición, no solo en la primera.

Un detalle que se pasa por alto: el acceso por enlace no propaga las cabeceras de identidad del usuario a la aplicación de destino. No sirve, por tanto, para integrar la sesión con la aplicación que hay detrás. Para eso, un proveedor de identidad propio como Pocket ID con llaves de acceso encaja mejor.

Qué mirar cuando un recurso no responde

Por orden de probabilidad:

  1. El DNS no resuelve. El comodín tarda en propagarse. Comprueba el subdominio concreto, no solo el dominio raíz.
  2. El certificado no se emite. Casi siempre es el puerto 80 cerrado, o el correo de ejemplo sin sustituir en el fichero de Traefik.
  3. El sitio aparece desconectado. Mira el registro de Newt en tu red. Si sale una y otra vez, es el UDP 51820 bloqueado en el VPS.
  4. El túnel está bien y el recurso da error 502. El destino apunta a una dirección que Newt no alcanza. Recuerda que resuelve desde tu red, no desde el VPS.
  5. Todo funciona salvo el cliente de escritorio. Falta el UDP 21820, que es el que usa el repetidor cuando la perforación de NAT no sale.
  6. Direcciones que se pisan. Si tu red usa el rango 100.64.0.0/10, el bloque por defecto de Gerbil colisiona y ya no se puede cambiar sin rehacer el registro.

Pangolin frente a Cloudflare Tunnel y frente a una malla de WireGuard

Las tres opciones evitan abrir un puerto. Se diferencian en quién ve tu tráfico y en qué te cuesta.

Pangolin Cloudflare Tunnel Malla de WireGuard
Conexión saliente desde tu red Sí Sí Sí
Infraestructura que mantienes Un VPS Ninguna Un nodo coordinador
Quién descifra el tráfico Tu VPS Cloudflare Nadie por el camino
Acceso desde un navegador ajeno Sí Sí No, hace falta cliente
Identidad y reglas por recurso Integradas Con Cloudflare Access Fuera del alcance
Límite de subida El de tu VPS 100 MB en los planes gratuito y Pro El de tu enlace
Coste mensual El del VPS Cero Cero o el del nodo

Ese límite de subida está documentado por la propia Cloudflare: 100 MB en los planes gratuito y Pro[3], 200 MB en Business y 500 MB o más en Enterprise. Si publicas un Immich o un Nextcloud, lo vas a encontrar el primer día.

Contra la malla, la comparación es distinta. Headscale o wg-easy te dan acceso privado entre tus propias máquinas, cifrado de extremo a extremo, sin intermediario que descifre nada. Lo que no te dan es una dirección que puedas mandar por correo a alguien que jamás instalará un cliente de red privada. Pangolin cubre los dos casos, con recursos públicos por navegador y recursos privados por cliente, y por eso su repositorio se describe hoy como red privada y proxy inverso a la vez.

Ahora la parte incómoda, y la documentación de Pangolin la escribe sin adornos: "By tunneling out to the VPS, you are effectively including the VPS in your security boundary, so you must secure it as part of your overall network strategy". Ese servidor deja de ser una caja alquilada y pasa a ser parte de tu red. Sus actualizaciones, su tiempo de servicio y su factura de tráfico son ahora responsabilidad tuya. Con Cloudflare eso lo lleva otro; el precio es que ese otro ve tus peticiones en claro.

Para quién es Pangolin y para quién no

Tiene sentido si publicas más de un servicio, quieres una sola pantalla de acceso delante de todos y te molesta que un tercero termine tu TLS. No lo tiene si publicas uno solo y no te importa que Cloudflare lo vea, porque estarías pagando un VPS por nada. Tampoco si tu requisito es que nadie ajeno pueda siquiera intentar entrar: eso lo hace mejor una malla cerrada como la alternativa libre a Tailscale.

Conviene además saber dónde está la línea de la edición libre. La Community Edition es AGPL-3 y desde la versión 1.22.0 incluye los recursos de SSH, RDP y VNC por navegador, además de HTTP y SSH privados. La Enterprise, con agrupación de nodos para alta disponibilidad, va con licencia comercial: gratuita por debajo de 100.000 dólares de facturación anual, de pago por encima. Un nodo suelto sigue siendo un punto único de fallo.

Preguntas frecuentes

¿Necesito abrir algún puerto en mi router?

No. El conector Newt inicia las dos conexiones hacia el VPS, una por WebSocket y otra por WireGuard. Los puertos que hay que abrir están en el VPS, no en tu casa. Tampoco necesitas IP fija ni DNS dinámico.

¿Puedo usar Pangolin sin túnel, como proxy inverso normal?

Sí. El instalador pregunta si quieres Gerbil, y hay un modo documentado sin túnel en el que se elimina ese contenedor y Traefik publica los puertos directamente. En ese caso pierdes la parte del conector y te queda un proxy inverso con autenticación.

¿Qué pasa si el VPS se cae?

Se cae todo lo que publicabas. La edición libre corre en un solo nodo y no tiene agrupación, así que el VPS es un punto único de fallo. La alta disponibilidad con más de un nodo es una función de la edición Enterprise.

Conclusión

Instalar Pangolin son cuatro ficheros, tres contenedores y un conector. Lo que compras con ese trabajo es un punto de entrada que controlas tú, con identidad integrada y certificados automáticos, sin abrir un puerto en casa. Lo que pagas es un VPS que ahora forma parte de tu perímetro y que tienes que cuidar como tal.

Si esa cuenta te sale, es la mejor respuesta que hay hoy para publicar servicios domésticos sin depender de nadie. La versión en inglés de esta guía está en How to install Pangolin.

Fuentes

  1. fosrl/pangolin
  2. WireGuard
  3. 100 MB en los planes gratuito y Pro
  4. Pangolin, despliegue manual con Docker Compose
  5. Pangolin, DNS y red
  6. Pangolin, arquitectura del sistema
  7. Pangolin, instalar el conector Newt
  8. Pangolin, autenticación de recursos públicos
  9. Pangolin, edición Enterprise
  10. fosrl/newt, versiones publicadas