If you run a home server or self-hosted lab and you are stuck behind a CGNAT or a restrictive ISP, you already know the frustration of not being able to expose services without complicated port forwarding rules or relying on proprietary platforms. Pangolin fixes that problem by giving you a fully self-hosted, WireGuard-backed tunneled reverse proxy that you own and control entirely. This guide walks you through a complete install Pangolin on Debian 13 setup from a clean server to a working tunnel, including DNS, firewall configuration, the installer walkthrough, site creation, and connecting your first remote device using Newt. By the end of this tutorial, you will have a production-ready Pangolin stack running on Debian 13 “Trixie” with automatic SSL via Let’s Encrypt, a web dashboard, and a secure tunnel to any device you manage.

What Is Pangolin and Why Should You Care?

Pangolin is an open-source, self-hosted alternative to closed-source services like Cloudflare Tunnels and Tailscale. It punches through firewalls and CGNAT without requiring you to open a single inbound port on your home router, and it does this using WireGuard as the underlying tunnel protocol.

The stack ships with four core components working together:

• Pangolin – the control plane and web dashboard
• Gerbil – the tunnel manager, equivalent to Cloudflare’s cloudflared daemon
• Traefik – the reverse proxy layer that handles HTTP/HTTPS routing and SSL
• Newt – the lightweight client agent installed on the remote device you want to expose

What makes Pangolin stand out from similar tools is its built-in centralized authentication. You get SSO out of the box, which means you do not need to bolt on Authelia, Authentik, or Cloudflare Zero Trust separately. Every resource you expose can sit behind a login wall with a single toggle.

Pangolin is available in two editions: Community Edition (free, fully open-source) and Enterprise Edition (paid, with additional features). This guide uses the Community Edition.

Why Debian 13 Trixie for This Setup?

Debian 13 “Trixie” ships with Linux kernel 6.12 LTS, GCC 14.2, APT 3.0, and systemd 257, giving you a rock-solid, long-term-support foundation for server workloads. Debian’s philosophy of stability-over-bleeding-edge is exactly what you want for a tunnel proxy that needs to stay online continuously. Pangolin officially supports Debian-based systems, so every dependency, Docker package, and system service installs cleanly without workarounds.

Prerequisites

Before you start this Pangolin on Debian 13 setup, confirm you have the following ready:

• A VPS or dedicated server running Debian 13 (Trixie) with a public IP address
• Root or sudo access via SSH
• Minimum hardware: 1 GB RAM, 25 GB storage
• A registered domain name with access to its DNS control panel (Cloudflare, Namecheap, Porkbun, etc.)
• Four open ports on both your host firewall and your cloud provider’s external firewall:
  • 80/TCP and 443/TCP (HTTP/HTTPS via Traefik)
  • 51820/UDP and 21820/UDP (WireGuard tunnels via Gerbil)
• An email address for Let’s Encrypt SSL certificate generation and admin login
• Basic Linux terminal familiarity (the ability to run commands and edit files with nano)

Step 1: Update Your Debian 13 System

Always start a fresh server by pulling the latest packages. This prevents dependency conflicts and ensures your APT 3.0 package manager is operating cleanly.

Run both commands in sequence:

sudo apt update
sudo apt upgrade -y

If the upgrade installs a new kernel, reboot your server before continuing:

sudo reboot

Wait 30 seconds, reconnect over SSH, and verify you are back in your session before moving to the next step.

Step 2: Install Required Dependencies

The Pangolin installer relies on four tools to auto-detect your system architecture and pull the correct binaries. Install them all at once:

sudo apt install wget sed curl jq -y

Here is what each tool does during the install process:

• curl – fetches the installer script and queries the GitHub API for version numbers
• wget – downloads the Pangolin installer binary from GitHub Releases
• jq – parses the JSON response from GitHub to extract the latest version tag automatically
• sed – reformats CPU architecture strings (e.g., converts x86_64 to amd64) so the correct binary is downloaded

These four utilities allow the installer to be fully automated and architecture-aware, supporting both AMD64 (standard VPS) and ARM64 (Raspberry Pi, ARM-based VPS) systems.

Step 3: Configure Your Firewall

Pangolin requires four specific ports to be open. Using UFW (Uncomplicated Firewall) is the fastest way to configure this on Debian 13. Run each command separately:

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 51820/udp
sudo ufw allow 21820/udp
sudo ufw enable

Critical: If you are using a cloud provider like DigitalOcean, Vultr, AWS, or Hetzner, you must also open these same ports in the cloud provider’s external firewall panel (often called “Security Groups” or “Firewall Rules”). Host-level UFW rules alone are not enough if the provider blocks traffic before it reaches your server.

Confirm UFW status and active rules with:

sudo ufw status verbose

Step 4: Configure DNS Records for Your Domain

DNS configuration must be completed before running the installer. The Let’s Encrypt certificate validation process requires your domain to resolve to your server.

Set up the following DNS records with your provider:

• A Record: Point pangolin.yourdomain.com to your server’s public IP address. This will be the address for your Pangolin dashboard.
• Wildcard A Record: Point *.yourdomain.com to the same IP. This routes every new subdomain you create to your server automatically, so you do not need to add a new DNS record every time you expose a service.

Not all DNS providers support wildcard records. Both Cloudflare and Namecheap do, and both are good choices if you are still picking a registrar.

Verify your DNS record resolves correctly before continuing:

ping pangolin.yourdomain.com

DNS propagation usually takes a few minutes but can take up to 24 hours in rare cases. Do not proceed until the ping resolves to your server’s IP.

Step 5: Create the Pangolin Installation Directory

The Pangolin installer places all of its configuration files in the current working directory when you run it. This means you need to create and move into your target directory first.

Create the directory:

sudo mkdir -p /opt/pangolin

Move into it:

cd /opt/pangolin

The /opt/ path follows the Linux Filesystem Hierarchy Standard as the correct location for optional software not managed by your package manager. This keeps your Pangolin files cleanly separated from system packages.

Step 6: Download the Pangolin Installer

You have two methods. The quick method is the one Pangolin’s official documentation recommends.

Quick Method (Recommended)

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

Manual Method (For Version-Controlled Setups)

If you want explicit control over which version you download, use these commands instead.

First, detect the latest release:

VERSION=$(curl "https://api.github.com/repos/fosrl/pangolin/tags" | jq -r '.[0].name')

Then detect your CPU architecture:

CPU=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')

Then download the matching installer binary:

wget -O installer "https://github.com/fosrl/pangolin/releases/download/$VERSION/installer_linux_$CPU"

The VERSION and CPU variables work together so you never have to manually look up which binary to grab.

Step 7: Grant Execute Permissions and Run the Installer

Linux does not grant execute permission to downloaded files by default. This is a security feature. Grant it manually:

sudo chmod +x ./installer

Verify the permission was applied:

ls -la installer

You should see an x bit in the permissions column (e.g., -rwxr-xr-x). Now launch the installer:

sudo ./installer

Walking Through the Installer Prompts

The installer runs interactively. Work through each prompt in order.

Basic Configuration:

1. Edition – Choose Community Edition for the free, open-source version.
2. Base Domain – Enter only the root domain, no subdomain. Example: example.com not pangolin.example.com.
3. Dashboard Domain – Press ENTER to accept the default pangolin.example.com, or type a custom subdomain.
4. Let’s Encrypt Email – Enter a real email address. Let’s Encrypt will use this to notify you about certificate expiry.
5. Enable Gerbil Tunneling – Type yes or press ENTER. Skipping this turns Pangolin into a plain reverse proxy without tunnel support.

Admin User Setup:

6. Admin Email – The email you will use to log into the dashboard.
7. Admin Password – Must meet all four requirements:
   • At least one uppercase letter
   • At least one lowercase letter
   • At least one digit (0-9)
   • At least one special character (!@#$%)
8. Enter the password a second time to confirm.

Security Settings:

9. Disable signup without invite – Set to yes. This prevents anyone from self-registering on your instance.
10. Disable users from creating organizations – Leave as default no unless you are running a strictly single-user setup.

Email Configuration:

11. Enable SMTP email – Press ENTER to skip (no). You can configure this later from the dashboard.

Final Installation Steps:

12. Install Docker – If Docker is not already on your system, type yes. Docker is required for Pangolin to run.
13. Install and start containers – Type yes. This pulls the pangolin, gerbil, and traefik images and starts them. This step takes 2-3 minutes depending on your connection.
14. Install CrowdSec – Press ENTER to skip for now (no). CrowdSec adds intrusion detection but can be added later.

When the process finishes, you will see:

Installation complete!

Step 8: Access the Dashboard and Create Your First Site

Access the Pangolin Dashboard

Open a browser and navigate to:

https://<your-dashboard-domain>/auth/initial-setup

SSL is automatically configured via Let’s Encrypt. If your browser shows an insecure warning on the first visit, wait 2-3 minutes for the certificate to fully validate, then hard refresh.

Log in using the admin email and password you set during the installer prompts.

Create an Organization

On first login, Pangolin asks you to create an organization. An organization is the top-level container that holds all of your sites and resources.

• Name – A human-readable label, e.g., Home Lab
• ID – A unique slug with no spaces or special characters, e.g., homelab

Click Create Organization to proceed.

Create a Site

A site represents one remote network location. One Newt agent per site handles routing for everything accessible from that device’s network.

1. Give the site a descriptive name, e.g., Raspberry Pi, Office Server, or Home NAS.
2. Select Newt as the tunnel type. This is the simplest and most reliable option.
3. Copy down the three values Pangolin generates:
   • Newt Endpoint – The URL of your Pangolin instance
   • Newt ID – A unique identifier for this site
   • Newt Secret Key – The cryptographic key used to authenticate the tunnel

You will need all three values in the next step.

Connect Newt to Establish the Tunnel

Option A: Docker Method (Recommended)

Create a directory for Newt:

sudo mkdir -p /opt/stacks/newt
cd /opt/stacks/newt

Create a Compose file:

sudo nano compose.yaml

Add the following content, replacing the three placeholder values with your actual Newt Endpoint, ID, and Secret:

services:
  newt:
    image: fosrl/newt
    container_name: newt
    restart: unless-stopped
    environment:
      - PANGOLIN_ENDPOINT=<ENDPOINT>
      - NEWT_ID=<ID>
      - NEWT_SECRET=<SECRET>

Save and exit (CTRL+X, then Y, then ENTER), then start Newt:

docker compose up -d

Option B: Native systemd Binary

Download Newt directly:

VERSION=$(curl "https://api.github.com/repos/fosrl/newt/tags" | jq -r '.[0].name')
CPU=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
sudo wget -O /usr/local/bin/newt "https://github.com/fosrl/newt/releases/download/$VERSION/newt_linux_$CPU"
sudo chmod +x /usr/local/bin/newt

Create a systemd service:

sudo nano /lib/systemd/system/newt.service

[Unit]
Description=Newt
After=network.target

[Service]
ExecStart=/usr/local/bin/newt --id <ID> --secret <SECRET> --endpoint <ENDPOINT>
Restart=always
User=root

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl enable newt
sudo systemctl start newt

Return to the Pangolin dashboard, navigate to Sites, and confirm the status shows Online.

Add Your First Resource

Navigate to Resources in the sidebar, then click Add Resource. Fill in the following fields:

• Name – A label for this service, e.g., Nginx or Nextcloud
• Site – Select the site you just created
• Type – Choose HTTPS Resource for web apps, or Raw TCP/UDP Resource for game servers and raw network services
• Subdomain – The URL prefix users will access, e.g., nginx.yourdomain.com

Set the Target details:

• Method – HTTP or HTTPS depending on how the service runs locally
• IP/Hostname – Use localhost if the service runs on the same machine as Newt, or the LAN IP if it runs on a different device
• Port – The port number the service listens on, e.g., 80 for Nginx

SSO authentication is enabled by default. Leave it on to keep your services protected behind the Pangolin login.

Step 9: How to Update Pangolin on Debian 13

Keeping Pangolin current is straightforward. Move into your install directory and fetch the latest version numbers for all three components:

cd /opt/pangolin

Get the latest Pangolin version:

curl -s "https://api.github.com/repos/fosrl/pangolin/tags" | jq -r '.[0].name'

Get the latest Gerbil version:

curl -s "https://api.github.com/repos/fosrl/gerbil/tags" | jq -r '.[0].name'

Get the latest Traefik version:

curl -s "https://api.github.com/repos/traefik/traefik/tags" | jq -r '.[0].name'

Write down all three version numbers. Open the Docker Compose file:

sudo nano docker-compose.yaml

Update the image: tag for each service with the new version number:

image: fosrl/pangolin:1.4.0
image: fosrl/gerbil:1.0.0
image: traefik:v3.4.0

Pull the new images and restart:

docker compose pull
docker compose up -d

Always back up the /opt/pangolin directory before any update and check Pangolin’s GitHub release notes for breaking changes.

Troubleshooting Common Issues on Debian 13

Even on a clean Linux server tutorial setup, a few things can go wrong. Here are the six most common problems and their fixes:

Congratulations! You have successfully installed Pangolin. Thanks for using this tutorial for installing the Pangolin on Debian 13 “Trixie” system. For additional help or useful information, we recommend you check the official Pangolin website.