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:**
```bash
# 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:**
```bash
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`