pangolin/MOBILE-CLIENT-SETUP.md

Pangolin Mobile Client Setup Guide

Date: 2026-01-20 22:26:00+00:00 Device: Android (pixel9pro, pixel6pro) Current: Connected to 10.50.0.0/24 via WLAN Goal: Access services via Pangolin tunnel when on WAN/mobile network

---

Prerequisites

Before Setting Up Mobile:

• ✅ Pangolin control plane running (https://tunnel.obr.sh)
• ✅ Authentik SSO configured with Pangolin
• ⏸️ At least one site created in Pangolin (brn-home)
• ⏸️ At least one resource configured (e.g., Jellyfin)

Without sites/resources, the tunnel works but has nothing to access.

---

Part 1: Install Pangolin Mobile App

Android (Google Play Store)

App Name: Pangolin

Install:

1. Open Google Play Store on pixel9pro or pixel6pro
2. Search for "Pangolin"
3. Install the official Pangolin app (by fosrl)
4. Open the app

Alternative: F-Droid (if available)

---

Part 2: Enroll Mobile Device

Option A: QR Code Enrollment (Easiest)

On Desktop (accessing Pangolin dashboard):

1. Login to Pangolin: https://tunnel.obr.sh

   • Use your Pangolin admin account
   • Or "Login with Authentik" if SSO configured

2. Navigate to: Clients or Devices (left sidebar)

3. Click: Add Client or Enroll Device

4. Select: Mobile Device

5. QR Code appears on screen

On Mobile (pixel9pro/pixel6pro):

1. Open Pangolin app
2. Tap: Scan QR Code or Add Server
3. Point camera at QR code on desktop
4. Automatic enrollment - device connects
5. App may prompt for permissions (VPN, notifications) - ALLOW these

Done! Device enrolled and connected.

---

Option B: Manual Enrollment

On Mobile App:

1. Open Pangolin app

2. Tap: Add Server or Manual Setup

3. Enter server details:

   Server URL: https://tunnel.obr.sh
   

4. Tap Continue

5. Login with Authentik (if SSO configured):

   • Browser opens to Authentik login
   • Enter: akadmin / (password)
   • Enter MFA code
   • Approve access
   • Returns to app

6. Device enrolled and tunnel connected

---

Part 3: Access Services Through Tunnel

Once connected, the Pangolin app creates a VPN tunnel.

Accessing Jellyfin via Tunnel

On Mobile (when NOT on home WiFi):

1. Ensure Pangolin tunnel is connected:

   • Open Pangolin app
   • Should show "Connected" status
   • May show data transfer stats

2. Open browser on mobile (Chrome, Firefox, etc.)

3. Navigate to: https://video.obnh.io

4. Jellyfin loads through the tunnel!

   • Traffic: Mobile → WAN → tunnel.obr.sh (brn) → WireGuard tunnel → jellyfin:8096
   • Encrypted end-to-end
   • No public exposure

5. Login to Jellyfin:

   • If SSO configured: Click "Login with Authentik"
   • If not: Use Jellyfin credentials
   • Or use Quick Connect (6-digit code from web)

Accessing Other Services

Through Pangolin tunnel, you can access:

OpenWebUI: https://ll.obr.sh Transmission: https://tor.obnh.network Pi-hole Admin: https://dns.obnh.io Guacamole (RDP in browser!): https://remote.obr.sh/guacamole/

All work the same way:

• Connect Pangolin VPN
• Open mobile browser
• Navigate to service URL
• Authenticate (SSO or service-specific login)

---

Part 4: Understanding Pangolin Tunnel Behavior

When on Home WiFi (10.50.0.0/24):

Pangolin tunnel OFF:

• Services accessible directly via LAN
• Faster (no tunnel overhead)
• More battery efficient

Pangolin tunnel ON (optional):

• Still works, routes through tunnel
• No advantage when on home network
• Can leave on for convenience

When on Mobile Network / External WiFi:

Pangolin tunnel REQUIRED:

• Services only accessible through tunnel
• Encrypted WireGuard connection
• Appears as if you're on home LAN to services

Without tunnel:

• Services unreachable (after Traefik restrictions applied)
• Or requires public WAN exposure (less secure)

---

Part 5: Pangolin App Features

Connection Management

Toggle Tunnel:

• Tap connection to enable/disable
• Green = connected
• Grey = disconnected

Auto-Connect:

• Settings → Auto-connect on mobile data
• Automatically connects when off home WiFi

Kill Switch:

• Settings → Block internet when tunnel down
• Prevents leaking traffic if tunnel fails

Resource Access

Pangolin can show available resources:

• List of services you can access
• Quick links to open in browser
• Connection status per service

VPN Configuration

Pangolin uses WireGuard under the hood:

• Android VPN permission required
• Shows in notification area when connected
• Can view connection stats (data transfer, latency)

---

Part 6: Mobile App Troubleshooting

Cannot Enroll Device

Check:

• Pangolin dashboard accessible from mobile (https://tunnel.obr.sh)
• Firewall allows UDP 51821 (already configured on brn)
• Mobile has internet connectivity

Try:

• Use manual enrollment instead of QR
• Check Pangolin dashboard logs for connection attempts

Tunnel Connects But Services Unreachable

Check:

• Sites created in Pangolin dashboard
• Resources configured for services
• Newt client running on brn (connects services to Pangolin)

Deploy Newt on brn:

# Get command from Pangolin dashboard: Sites → brn-home → Connection
# Will look like:
docker run -d --name newt --cap-add NET_ADMIN \
  -e SITE_TOKEN="<from_dashboard>" \
  -e PANGOLIN_URL="https://tunnel.obr.sh" \
  --network traefik \
  fosrl/newt:latest

Battery Drain

Pangolin tunnel uses some battery:

• Normal: 5-10% extra per day
• High drain: Check for constant reconnections

Optimize:

• Disable tunnel when on home WiFi
• Use WiFi calling if available
• Enable battery optimization for Pangolin app (Android settings)

---

Part 7: Security Considerations

When Using Mobile Tunnel

Encrypted:

• ✅ WireGuard encryption (end-to-end)
• ✅ TLS for HTTPS services
• ✅ Double encryption for services

Authentication:

• ✅ Authentik SSO if configured
• ✅ Service-specific auth (Jellyfin, etc.)
• ✅ MFA on Authentik login

Safe To Use On:

• Public WiFi (coffee shop, airport)
• Hotel networks
• Mobile data
• Any untrusted network

What Gets Tunneled

Through Pangolin:

• Only traffic to configured Pangolin resources
• Example: video.obnh.io, ll.obr.sh, etc.

NOT tunneled:

• General internet traffic (Google, YouTube, etc.)
• Other apps on phone
• System updates

This is NOT a full VPN - it's a tunneled reverse proxy for specific services.

---

Part 8: Multi-Device Support

Setting Up pixel6pro (Second Device)

Same process:

1. Install Pangolin app
2. Scan QR code from dashboard (generates new enrollment)
3. Or use manual enrollment
4. Each device gets unique WireGuard keys
5. Both can connect simultaneously

Device Management:

• View all devices in Pangolin dashboard (Clients section)
• Revoke access per device if phone lost/stolen
• See last connection time per device

---

Part 9: Accessing Guacamole RDP on Mobile

This is REALLY cool:

On Mobile (connected to Pangolin tunnel):

1. Open browser: Chrome or Firefox
2. Navigate to: https://remote.obr.sh/guacamole/
3. Login (guacadmin or Authentik SSO)
4. Click: argon-rdp connection (after you create it)
5. Your Windows 11 desktop IN YOUR MOBILE BROWSER!
   • Full RDP session
   • Touch controls translated to mouse/keyboard
   • Can copy/paste between mobile and Windows
   • Can transfer files (if configured)

Use Cases:

• Remote desktop from anywhere
• Emergency Windows access
• Run Windows-only apps from phone
• Access files on Windows machine

---

Part 10: Jellyfin Mobile App Through Tunnel

Jellyfin official app + Pangolin tunnel:

Setup:

1. Install Jellyfin app (Google Play)
2. Connect Pangolin tunnel first
3. Open Jellyfin app
4. Add server: https://video.obnh.io
5. Quick Connect:
   • App shows 6-digit code
   • On desktop browser: Login to Jellyfin → Dashboard → Devices
   • Enter the 6-digit code
   • Device authorized
6. Jellyfin app now connected through tunnel

Benefits:

• Better than browser (native video player)
• Downloads for offline viewing
• Better performance
• Background audio playback

---

Quick Reference Card

Pangolin Connection:

Server: https://tunnel.obr.sh
Login: Authentik SSO (akadmin)
Protocol: WireGuard
Port: 51821/UDP

Services Through Tunnel:

Jellyfin:     https://video.obnh.io
OpenWebUI:    https://ll.obr.sh
Transmission: https://tor.obnh.network
Pi-hole:      https://dns.obnh.io
Guacamole:    https://remote.obr.sh/guacamole/

When to Connect:

• On mobile data: ✅ Connect
• On public WiFi: ✅ Connect
• On home WiFi (10.50.0.x): ⏸️ Optional (direct LAN access)

---

Next Steps

1. Complete 2 WebUI steps (see above - 5 minutes total)

2. Provide credentials to automation:

cat /home/olaf/pangolin/oidc-pangolin.txt

3. I will then:

• Create all other OIDC providers via Authentik API
• Configure all services programmatically
• Create Pangolin sites and resources
• Provide final mobile enrollment QR code

4. Install Pangolin app and enroll (2 minutes)

5. Test accessing Jellyfin from mobile data (1 minute)

Total setup time: ~15 minutes start to finish

---

File: /home/olaf/pangolin/MOBILE-CLIENT-SETUP.md

Start with: Complete Step 1 in /home/olaf/pangolin/WEBUI-ONLY-STEPS.md