Broski

Network Issues

Diagnose and fix network connectivity problems between your phone and your system.

Run Diagnostics First

Always start with focused doctor profiles:

bash
broski doctor --profile network
broski doctor --profile pairing
broski doctor --fix

This checks local IP, configured port conflicts, Tailscale status, token/TLS pairing readiness, and suggests fixes.

Local Connection (Same WiFi)

Can't connect on local network

Most common issues:

  1. Different networks: Ensure phone and system are on the same WiFi network
  2. 5GHz vs 2.4GHz: Some routers isolate these bands - try connecting both devices to the same band
  3. Firewall blocking: macOS firewall may block incoming connections
  4. Client isolation: Some routers isolate wireless clients from each other
Test connectivity quickly
bash
# Network diagnostics
broski doctor --profile network

# Pairing readiness (token + TLS)
broski doctor --profile pairing

# Live logs while reproducing issue
broski logs --follow

Corporate Network / Firewall

Corporate networks often block peer-to-peer connections
If you're on a work network, local connections may be blocked. Use Tailscale instead.

Symptoms

  • • Can't connect even though both devices are on the same WiFi
  • • Connection works at home but not at office
  • • QR code scans but connection times out

Solutions

Option 1: Use Tailscale (Recommended)

Tailscale creates an encrypted tunnel that bypasses corporate restrictions:

bash
# Guided install/configure
broski setup-tailscale

# Then verify network path
broski doctor --profile network

Install Tailscale on your phone and log in with the same account.

Option 2: Request firewall exception

Ask IT to allow traffic on port 18274 between wireless clients, or to whitelist the bridge application.

Option 3: Use mobile hotspot

Create a mobile hotspot from your phone and connect your system to it. This bypasses corporate network entirely.

VPN Conflicts

VPNs can interfere with local connections
When a VPN is active, your system's local IP may change or become unreachable from your phone.

Symptoms

  • • Connection worked before enabling VPN
  • • QR code shows different IP than expected
  • • High latency when VPN is active

Solutions

ScenarioSolution
Corporate VPN activeDisconnect VPN or use Tailscale
Split tunnel availableExclude local IPs from VPN
Tailscale + other VPNTailscale usually works alongside other VPNs
VPN changes routingUse Tailscale IP instead of local IP

Check VPN Status

bash
# Check active network interfaces
# macOS:
ifconfig | grep -A 2 "utun"  # VPN tunnels are usually utun*
# Windows:
# ipconfig
# Linux:
# ip addr show

# Check routing table for VPN routes
# macOS:
netstat -nr | grep -i utun
# Windows:
# route print
# Linux:
# ip route show

# See all network interfaces
# macOS:
networksetup -listallnetworkservices
# Windows:
# netsh interface show interface
# Linux:
# nmcli device status

Tailscale Issues

Tailscale not connecting
bash
# Check Tailscale status
tailscale status

# Check your Tailscale IP
tailscale ip

# Verify connection to tailnet
tailscale ping <other-device-tailscale-ip>

# Check if Tailscale is logged in
tailscale status --json | jq '.Self.Online'
Both devices must be on Tailscale

For Tailscale to work, both your system and phone must:

  • Have Tailscale installed
  • Be logged into the same Tailscale account (same tailnet)
  • Be connected (not disconnected/paused)
Tailscale relayed vs direct
bash
# Check connection type
tailscale status

# Look for "relay" in output - this means no direct connection
# Direct connections are faster and more reliable

If showing "relay", check firewall settings on both devices to allow direct connections.

Port Forwarding

Port forwarding is NOT recommended
Exposing the bridge to the public internet is a security risk. Use Tailscale or Tailscale Funnel instead.

If you must use port forwarding (e.g., for testing), here's how:

1
Find your system's local IP
bash
# macOS:
ifconfig | grep "inet " | grep -v 127.0.0.1
# Windows:
# ipconfig
# Linux:
# ip addr show | grep "inet " | grep -v 127.0.0.1
2
Log into your router's admin panel

Usually at 192.168.1.1 or 192.168.0.1

3
Find Port Forwarding settings

Often under Advanced, NAT, or Gaming settings

4
Create a port forward rule

External port: 18274, Internal port: 18274, Internal IP: your system's IP, Protocol: TCP

5
Find your public IP
bash
curl ifconfig.me
6
Connect using public IP

Use the public IP in your connection URL instead of the local IP

Better alternative: Tailscale Funnel
Instead of port forwarding, use Tailscale Funnel for secure public access:
bash
broski --funnel

Testing Connectivity

bash
# 1) Baseline diagnostics
broski doctor --profile network

# 2) Pairing path diagnostics
broski doctor --profile pairing

# 3) Apply safe fixes
broski doctor --fix --profile network

# 4) Follow logs while reproducing issue
broski logs --follow

# 5) Export diagnostics for support/AI
broski logs --export

Connection Drops

Frequent disconnections

Common causes:

CauseSolution
WiFi switchingLock your phone to a specific WiFi network
Sleep modePrevent your system from sleeping while using Broski
App backgroundedKeep Broski in foreground on iOS
Network instabilityMove closer to router or use wired connection
High latencySwitch from Funnel to Tailscale direct
Auto-reconnect behavior

The app automatically attempts to reconnect with exponential backoff (2s, 4s, 8s, 16s, max 30s). If you see "Reconnecting...", wait for it to complete. You can also manually tap to reconnect or re-scan the QR code.

Latency Expectations

Connection TypeExpected LatencyBest For
Local WiFi1-30msHome/office use, best experience
Tailscale (nearby)30-50msSame city/region
Tailscale (distant)50-150msCross-country
Tailscale Funnel100-300msPublic access, no VPN needed

RTT (Round-Trip Time) is shown in the app's connection indicator. If latency is consistently high, try switching connection types.

Related

Remote Access

Set up Tailscale properly

Connection Issues

General connection troubleshooting