Part 3 of 6

Connecting Sites with Newt

Three deployment scenarios for connecting private networks to your Pangolin VPS via encrypted WireGuard tunnels.

25 minutes

Pangolin VPS + private server(s)

Newt is what makes Pangolin genuinely useful for most self-hosters: it lets you expose services from networks that have no public IP, no open ports, and no ability to accept inbound connections.

Understanding Sites

In Pangolin's terminology, a site is a connected private network. Each site has:

A unique Newt ID and secret key (like a WireGuard peer identity)
Its own set of resources accessible through it
A WireGuard IP address within Pangolin's internal network

Creating a Site in Pangolin

In the left navigation, click Sites
Click Create Site
Give it a name (e.g., "Home Lab", "Office Server")
Click Create

Newt credentials (shown once)

PANGOLIN_ENDPOINT=https://pangolin.yourdomain.com
NEWT_ID=2ix2t8xk22ubpf
NEWT_SECRET=a8f3k9x2m1q7p4n6

Copy these values now. The secret is only shown once.

Scenario 1: Newt on a Linux Home Server

The most common setup. The server needs outbound internet access on UDP 51820 and TCP 443 — no inbound ports required.

Download and install Newt

# Check architecture: uname -m (x86_64 = amd64, aarch64 = arm64)
curl -fsSL https://github.com/fosrl/newt/releases/latest/download/newt-linux-amd64 \
  -o /usr/local/bin/newt
chmod +x /usr/local/bin/newt

Create configuration

mkdir -p /etc/newt
cat > /etc/newt/config.env << 'EOF'
PANGOLIN_ENDPOINT=https://pangolin.yourdomain.com
NEWT_ID=2ix2t8xk22ubpf
NEWT_SECRET=a8f3k9x2m1q7p4n6
EOF
chmod 600 /etc/newt/config.env

Create systemd service

cat > /etc/systemd/system/newt.service << 'EOF'
[Unit]
Description=Newt - Pangolin Tunnel Connector
After=network-online.target
Wants=network-online.target

[Service]
EnvironmentFile=/etc/newt/config.env
ExecStart=/usr/local/bin/newt
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal
User=root

[Install]
WantedBy=multi-user.target
EOF

Enable and start

systemctl daemon-reload
systemctl enable newt
systemctl start newt
systemctl status newt

Scenario 2: Newt in Docker Compose

Add Newt to an existing Compose environment alongside your other containers:

docker-compose.yml addition

services:
  # ... your existing services ...

  newt:
    image: fosrl/newt:latest
    container_name: newt
    restart: unless-stopped
    environment:
      - PANGOLIN_ENDPOINT=https://pangolin.yourdomain.com
      - NEWT_ID=2ix2t8xk22ubpf
      - NEWT_SECRET=a8f3k9x2m1q7p4n6
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
    sysctls:
      - net.ipv4.conf.all.src_valid_mark=1

Container-to-Container Routing

For Newt to reach your other containers by name, put them on a shared Docker network:

Shared network pattern

networks:
  pangolin_bridge:
    driver: bridge

services:
  newt:
    image: fosrl/newt:latest
    networks:
      - pangolin_bridge
    environment:
      - PANGOLIN_ENDPOINT=https://pangolin.yourdomain.com
      - NEWT_ID=your-newt-id
      - NEWT_SECRET=your-newt-secret
    cap_add:
      - NET_ADMIN

  nextcloud:
    image: nextcloud:30-fpm
    networks:
      - pangolin_bridge
    # ... rest of config

With this setup, resource targets use container names: nextcloud:80

Scenario 3: Newt on a Remote VPS

Identical to Scenario 1 — SSH in and install Newt as a systemd service. The remote server connects outbound to your Pangolin VPS, just like a home server.

Benefits over direct proxying: zero-trust access control in one place, no need to open additional ports, all access logs centralized, encrypted transit for cleartext services.

Managing Multiple Sites

IP address conflicts: If your home and office both use 192.168.1.0/24, that's fine — Pangolin routes through the tunnel, not your existing network routing.
Site isolation: A resource on Site A can't "see" Site B's services. Each site is isolated.
Connection resilience: Newt reconnects automatically if the tunnel drops (network outage, VPS reboot, etc.).

Troubleshooting Newt Connectivity

Check Newt logs

# Systemd
journalctl -u newt -n 50

# Docker
docker compose logs newt

Verify outbound UDP connectivity

nc -zu <your-ramnode-vps-ip> 51820

Check WireGuard interface

ip addr show  # Look for a wg interface added by Newt

DNS resolution failure: Check DNS on the Newt server
UDP 51820 blocked: Some ISPs block WireGuard ports — Pangolin supports alternate ports
Time skew: WireGuard is sensitive to clock drift — ensure NTP is running

Part 2: Installation Part 4: Exposing Web Apps