Pangolin Setup: VPS-to-Home Tunnels

Why Pangolin Over Traditional Approaches

Pangolin is a three-component system developed by Fossorial (a Y Combinator 2025 company). Each component is named after a fossorial (burrowing) animal:

The traffic flow is straightforward: a user's browser connects to your VPS over HTTPS, Traefik terminates SSL and routes the request through the WireGuard tunnel managed by Gerbil, and the Newt client on your home network forwards it to the target service. Your home IP is never exposed, and no inbound ports need to be opened on your router.

Prerequisites

• • A VPS with a public IP address. RamNode's KVM Standard plan at $5/month (1 vCPU, 1 GB RAM, 12 GB SSD) is more than sufficient. Pangolin's three containers typically consume around 650 MB of RAM combined.
• • A domain name you control with access to DNS management. A wildcard A record (*.tunnel.yourdomain.com) simplifies adding services later, but a single subdomain works to start.
• • Ubuntu 24.04 LTS on the VPS (Debian 12, Fedora, RHEL, and Amazon Linux are also supported).
• • SSH access to your VPS with root or sudo privileges.
• • A home server or NAS capable of running Docker (a Raspberry Pi 4 or later works fine).
• • An email address for Let's Encrypt certificate registration.

Step 1: Provision and Harden Your VPS

Spin up a new KVM Standard instance on RamNode with Ubuntu 24.04 LTS. Once the server is online, SSH in and perform initial hardening:

ssh root@YOUR_VPS_IP

# Update packages
apt update && apt upgrade -y

# Create a non-root user
adduser deploy
usermod -aG sudo deploy

# Harden SSH
sed -i 's/#PermitRootLogin yes/PermitRootLogin no/' /etc/ssh/sshd_config
sed -i 's/#PasswordAuthentication yes/PasswordAuthentication no/' /etc/ssh/sshd_config
systemctl restart sshd

# Configure UFW firewall
ufw allow 22/tcp      # SSH
ufw allow 80/tcp      # HTTP (Let's Encrypt ACME challenge)
ufw allow 443/tcp     # HTTPS
ufw allow 51820/udp   # WireGuard tunnel
ufw enable

Step 2: Configure DNS

Point your domain to the VPS. At minimum, create these DNS records:

The wildcard record is optional but highly recommended. It means every new service you expose automatically gets a subdomain (jellyfin.tunnel.yourdomain.com, nextcloud.tunnel.yourdomain.com) without touching DNS again.

Step 3: Install Pangolin

Pangolin provides an official installer script that sets up Docker, Docker Compose, Pangolin, Gerbil, and Traefik in one pass. SSH into your VPS as the deploy user and run:

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

The installer walks you through an interactive configuration. Here's what each prompt expects:

• • Base Domain: Enter your root domain (e.g., yourdomain.com).
• • Dashboard Subdomain: The subdomain for the Pangolin admin UI (e.g., pangolin, giving you pangolin.yourdomain.com).
• • Let's Encrypt Email: A valid email for certificate registration and renewal notices.
• • Admin Email: The login email for the first Pangolin admin account.
• • Admin Password: Choose a strong password. You'll change this or add 2FA later.
• • Install CrowdSec: Select Yes — we'll configure it in depth in Part 4, but having the bouncer installed now saves time later.
• • SMTP Configuration: Optional but recommended for password resets and user invitations. You can configure this later in config.yml.

The installer typically takes two to three minutes. When it finishes, it will start the Docker containers automatically.

Step 4: Verify the Installation

Check that all three core containers are running:

sudo docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

You should see pangolin, gerbil, and traefik all showing "Up" status. Pangolin's health check endpoint should also respond:

curl -s http://localhost:3001/api/v1/ | head -c 100

Now open your browser and navigate to https://pangolin.yourdomain.com. You'll see the Pangolin login screen secured by a valid Let's Encrypt certificate. Log in with the admin credentials you set during installation.

Step 5: Create Your First Site

In Pangolin's terminology, a "Site" represents a remote network location where you'll run the Newt tunnel client. Your home network is your first site.

1. In the Pangolin dashboard, click Sites in the left navigation.
2. Click Add Site.
3. Give your site a recognizable name (e.g., "Home Lab").
4. The connection method defaults to Newt Tunnel — leave this selected.
5. Pangolin will generate three values: Newt Endpoint, Newt ID, and Newt Secret Key. Copy all three and store them securely.
6. Confirm that you have saved the credentials and complete the site creation.

Step 6: Deploy Newt on Your Home Server

Newt is Pangolin's lightweight WireGuard client that establishes the encrypted tunnel from your home network to the VPS. You have two deployment options: Docker (recommended) or a standalone binary.

Option A: Docker Deployment (Recommended)

On your home server, create a directory and Docker Compose file:

services:
  newt:
    image: docker.io/fosrl/newt:latest
    container_name: newt
    restart: unless-stopped
    environment:
      PANGOLIN_ENDPOINT: "https://pangolin.yourdomain.com"
      NEWT_ID: "your-newt-id"
      NEWT_SECRET: "your-newt-secret-key"
    network_mode: host

mkdir -p ~/pangolin-newt && cd ~/pangolin-newt
# Create docker-compose.yml with the above contents
docker compose up -d

Using network_mode: host is important because Newt needs to reach services on your local network by their LAN IP addresses.

Option B: Binary Deployment

If you prefer to avoid Docker on the home server, download the Newt binary directly:

wget -O newt "https://github.com/fosrl/newt/releases/latest/download/newt_linux_amd64"
chmod +x ./newt
./newt --server https://pangolin.yourdomain.com --id YOUR_NEWT_ID --token YOUR_NEWT_SECRET

For production use, create a systemd service so Newt starts automatically on boot:

[Unit]
Description=Pangolin Newt Tunnel Client
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/newt \
  --server       https://pangolin.yourdomain.com \
  --id YOUR_NEWT_ID \
  --token YOUR_NEWT_SECRET
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

sudo mv newt /usr/local/bin/
sudo systemctl daemon-reload
sudo systemctl enable --now newt

Step 7: Verify the Tunnel

Back in the Pangolin dashboard, navigate to the Sites page. Your "Home Lab" site should now show as online with a green indicator. The logs section will display successful connection messages:

INFO:   Websocket connected
INFO:   Received registration message
INFO:   Connecting to endpoint: pangolin.yourdomain.com
INFO:   Initial connection test successful!
INFO:   Tunnel connection to server established successfully!

You can also verify from the Newt side by checking Docker logs:

docker logs newt --tail 20

Understanding the Architecture

At this point, here's what you've built:

All traffic between your VPS and home network is encrypted via WireGuard. No ports are opened on your home router. The only publicly exposed ports are 80, 443, and 51820 on the VPS, which you've already locked down with UFW.

Troubleshooting Common Issues

What's Next