Skip to content

abyssbugg/LocationSpoofer

BranchesTags

Repository files navigation

LocationSpoofer

GPS Location Simulation for iOS 17+ Devices

macOS iOS Swift Tests License

Status: 🎉 Production Ready v1.0.0

LocationSpoofer is a production-grade macOS application for simulating GPS locations on iOS 17+ devices. Built with SwiftUI and powered by pymobiledevice3, it provides sub-50ms latency location updates with a beautiful, native macOS interface.

LocationSpoofer Screenshot

✨ Features

  • 🎯 Teleport Mode - Instantly jump to any coordinates worldwide
  • 🗺️ Route Playback - Follow GPX routes with configurable speed
  • 🕹️ Joystick Control - Real-time location movement with keyboard/joystick
  • 🔌 Multi-Mode Tunnel - USB, WiFi, Background Daemon, or Auto mode
  • ⚡ Rate Limiting - Token bucket algorithm (5 req/sec sustained)
  • 🏥 Health Monitoring - Auto-recovery with <50ms latency
  • 🔒 Security - Input validation, injection prevention, sanitization
  • ✅ Production Quality - 82 unit tests, >70% coverage

📦 Installation

Option 1: Build from Source (Recommended)

# Clone the repository
git clone https://github.com/yourusername/LocationSpoofer.git
cd LocationSpoofer

# Build the app bundle
cd LocationSpoofer
./build-app-bundle.sh

# Install to Applications
cp -R build/LocationSpoofer.app /Applications/

# Launch
open /Applications/LocationSpoofer.app

Option 2: Download Pre-Built App

  1. Download LocationSpoofer.dmg from Releases
  2. Open the DMG and drag LocationSpoofer to Applications
  3. Launch from Applications or Spotlight

🚀 Quick Start

Prerequisites

Required:

  • macOS 14.0 (Sonoma) or later
  • Python 3.9 or later
  • iOS device with iOS 17.0 or later
  • USB cable (for initial setup)

Install Python Dependencies:

# Install pymobiledevice3
python3 -m pip install -U pymobiledevice3

# Verify installation
pymobiledevice3 version  # Should be >= 6.1.5

First Run

  1. Enable Developer Mode on iOS:

    • Settings → Privacy & Security → Developer Mode → ON
    • Device will reboot - confirm "Turn On Developer Mode"

  2. Launch LocationSpoofer:

    • Open LocationSpoofer.app from Applications
    • Grant permissions if prompted

  3. Complete Onboarding:

    • App will guide you through 4 validation steps
    • Checks Python 3.9+, pymobiledevice3, device connection, tunnel

  4. Connect Device:

    • Plug in iOS device via USB
    • Click "Refresh Devices" in sidebar
    • Device should appear in device list

  5. Start Tunnel:

    • Click "Start Tunnel" button
    • Wait for "Connected" status (green indicator)

  6. Teleport Your First Location:

    • Select "Teleport" mode from sidebar
    • Click on map or enter coordinates:
      • Latitude: 35.6812
      • Longitude: 139.7671 (Tokyo Station)
    • Click "Teleport Now"
    • Open Maps on iOS device - you're now in Tokyo! 🗼

📖 Usage

Teleport Mode

Instantly jump to any location worldwide:

  1. Select Teleport from sidebar
  2. Choose method:
    • Click on map at desired location
    • Enter coordinates manually
    • Use quick locations (pre-configured landmarks)
  3. Click Teleport Now
  4. Location updates in <50ms on device

Quick Locations Included:

  • Tokyo Station (Japan)
  • Times Square, NYC (USA)
  • Eiffel Tower (France)
  • Sydney Opera House (Australia)
  • Big Ben (London, UK)

Route Mode

Follow a pre-defined path from GPX files:

  1. Select Route from sidebar
  2. Click Load GPX and select file
  3. Set playback speed (1-50 m/s)
  4. Click Start Route
  5. Route plays back with natural movement

Sample GPX Files:

  • Located in Resources/sample_routes/
  • Import your own from Strava, Google Maps, etc.

Joystick Mode

Real-time movement control:

  1. Select Joystick from sidebar
  2. Use controls:
    • Arrow Keys - Move in cardinal directions
    • Speed Slider - Adjust movement speed (1-50 m/s)
    • On-Screen Joystick - Click and drag for movement
  3. Location updates continuously while moving

⌨️ Keyboard Shortcuts

LocationSpoofer supports extensive keyboard shortcuts for efficient operation:

Location Commands

Shortcut Action
⌘L Set location at current coordinates
⌘K Clear current location
⌘R Refresh device list

Simulation Commands

Shortcut Action
⌘Space Start simulation
⌘P Pause simulation
⌘Esc Stop simulation

Navigation

Shortcut Action
⌘⇧S Toggle sidebar
⌘, Open settings

Speed Control

Shortcut Action
⌘⌥↑ Increase simulation speed
⌘⌥↓ Decrease simulation speed

Tip: A complete shortcuts reference is also available in Settings → Keyboard Shortcuts.

⚙️ Configuration

Tunnel Modes

LocationSpoofer supports 4 tunnel connection modes:

Mode Description Use Case
Auto Automatically selects best method Recommended default
USB (Lockdown) Direct USB connection Fastest (<30ms latency)
WiFi Wireless connection via same network No cable needed
Daemon Background service, auto-discovery Persistent connection

Change Mode: Settings → Tunnel Mode → Select preferred mode

Rate Limiting

Prevents device/network overload:

  • Burst: 10 requests (immediate)
  • Sustained: 5 requests/second
  • Auto-throttle: Queues excess requests

Customize in Settings → Advanced → Rate Limits

🧪 Testing

Run Unit Tests

cd LocationSpoofer
swift test

Test Coverage:

  • 82 tests total
  • 100% pass rate

  • 70% code coverage

Test Suites:

  • ArgumentSanitizerTests - Input validation (15 tests)
  • GPXParserTests - Route parsing (9 tests)
  • LocationCoordinateTests - Coordinate validation (13 tests)
  • PythonPathResolverTests - Dependency detection (6 tests)
  • RateLimiterTests - Token bucket algorithm (6 tests)
  • RouteInterpolatorTests - Route interpolation (17 tests)
  • TunneldManagerTests - Tunnel lifecycle (16 tests)

User Acceptance Testing

Follow the comprehensive UAT guide:

open UAT_GUIDE.md

10 Test Scenarios:

  1. First Launch & Onboarding
  2. Device Detection
  3. Tunnel Establishment
  4. Location Spoofing
  5. Rate Limiting
  6. Route Playback
  7. Joystick Control
  8. Multi-Mode Tunnel
  9. Health Monitoring
  10. Stress Test (30 min)

🛠️ Development

Build from Source

# Clone repository
git clone https://github.com/yourusername/LocationSpoofer.git
cd LocationSpoofer/LocationSpoofer

# Build debug version
swift build

# Build release version
swift build -c release

# Create app bundle
./build-app-bundle.sh

Project Structure

LocationSpoofer/
├── LocationSpoofer/           # Main app source
│   ├── UI/                    # SwiftUI views
│   ├── Core/                  # Services (RateLimiter, Logger, etc.)
│   ├── Device/                # Device communication & tunnel mgmt
│   ├── Models/                # Data models
│   ├── Simulation/            # Simulation engine
│   ├── GPX/                   # GPX parsing & route library
│   └── LocationSpooferApp.swift
├── Tests/                     # Unit tests (82 tests)
├── Resources/                 # App resources
│   ├── Info.plist
│   └── sample_routes/
├── build-app-bundle.sh        # App bundler script
└── Package.swift              # Swift Package manifest

Architecture

LocationSpoofer is a monolithic SwiftUI macOS app with integrated backend:

  • UI Layer - SwiftUI views with @ObservableObject state management
  • Service Layer - Core services (RateLimiter, TunneldManager, etc.)
  • Device Layer - pymobiledevice3 bridge, tunnel management
  • Data Layer - Models, GPX parsing, coordinate validation

No separate frontend/backend - all communication happens through @Published properties for optimal performance.

Data Flow Architecture

sequenceDiagram
    participant User
    participant UI as SwiftUI Views
    participant AppState as AppState (@MainActor)
    participant Bridge as DevLocationBridge
    participant Python as pymobiledevice3
    participant Device as iOS Device

    User->>UI: Click "Set Location"
    UI->>AppState: setLocation(coordinate)
    AppState->>AppState: Validate iOS version
    alt iOS 18+ Detected
        AppState->>UI: Show warning toast
    end
    AppState->>Bridge: setLocation(coordinate, device)
    Bridge->>Bridge: performPreflight()
    Bridge->>Bridge: Check rate limit
    Bridge->>Bridge: Sanitize arguments
    Bridge->>Python: Execute subprocess
    Note over Bridge,Python: pymobiledevice3 developer dvt<br/>simulate-location set
    Python->>Device: DVT Protocol (USB/WiFi)
    Device-->>Python: Success/Error
    Python-->>Bridge: stdout/stderr
    Bridge->>Bridge: Parse output
    alt Success
        Bridge-->>AppState: Location updated
        AppState-->>UI: Show success toast
    else Error
        Bridge-->>AppState: LocationInjectionError
        AppState-->>UI: Show error dialog
    end
Loading

Documentation

Document Purpose
DEVELOPER_GUIDE.md Complete developer documentation (553 lines)
UAT_GUIDE.md User acceptance testing procedures
FUTURE_ENHANCEMENTS.md Roadmap: Multi-device, CI/CD, advanced routes
PROGRESS.md Task completion tracking
SESSION_SUMMARY.md Detailed session records
PRODUCTION_READY_SUMMARY.md Production readiness verification

API Documentation (DocC)

LocationSpoofer includes comprehensive API documentation built with Apple's DocC:

Local Generation:

swift package generate-documentation \
  --target LocationSpoofer \
  --disable-indexing

Hosted Documentation: The CI pipeline automatically builds and deploys DocC documentation to GitHub Pages on every push to main:

  • URL: https://yourusername.github.io/LocationSpoofer/documentation/locationspoofer/
  • Build Status: Check the "Build Documentation" and "Deploy Documentation to GitHub Pages" jobs in CI workflow

Topics Covered:

  • Core Components (DevLocationBridge, DeviceManager, TunneldManager)
  • Simulation Modes (Teleport, Route, Joystick)
  • Device Management & Error Handling
  • Configuration & Reliability

Note: To enable GitHub Pages hosting, go to repository Settings → Pages → Source: GitHub Actions (not "Deploy from a branch"). The CI workflow uses the actions/deploy-pages action to deploy directly.

🔒 Security

LocationSpoofer implements multiple security layers:

  • Input Sanitization - All coordinates, UDIDs, ports validated
  • Command Injection Prevention - Subprocess arguments escaped
  • Path Traversal Protection - File paths sanitized
  • Rate Limiting - Prevents abuse and device overload
  • Process Timeout - 30s max for all subprocess operations

Security Audit:

  • ✅ No hardcoded secrets
  • ✅ No shell command injection vectors
  • ✅ All inputs validated with regex patterns
  • ✅ Subprocess arguments properly escaped

📊 Performance

Benchmarks (tested on MacBook Pro M1, iOS 17.6):

Metric Target Measured Status
Location Update Latency <50ms 28ms ✅
Tunnel Start Time <15s 8.2s ✅
Rate Limit (sustained) 5 req/s 5.1 req/s ✅
Memory Usage (30min) <150MB 87MB ✅
CPU Usage (avg) <20% 12% ✅
Test Suite Pass Rate 100% 100% ✅

🚧 Troubleshooting

Common Issues

1. "Tunnel failed to start"

Check Python and dependencies:

python3 --version  # Should be >= 3.9
python3 -m pip install -U pymobiledevice3
pymobiledevice3 version  # Should be >= 6.1.5

2. "Device not detected"

  • Ensure Developer Mode is enabled on iOS device
  • Unplug and reconnect USB cable
  • Click "Refresh Devices" in sidebar
  • Check pymobiledevice3 usbmux list in Terminal

3. "Location not updating in some apps"

  • Some apps use cellular/GPS instead of network location
  • Fix: Enable Airplane Mode + WiFi only on iOS device

4. macOS Full Disk Access required

System Settings → Privacy & Security → Full Disk Access → Enable for LocationSpoofer

5. "Operation not permitted" error

  • Cause: macOS security restrictions
  • Fix: Grant LocationSpoofer Full Disk Access (see #4)

6. iOS 18+ Compatibility Issues

LocationSpoofer is optimized for iOS 17.0-17.6. iOS 18+ devices may experience location injection failures due to Apple's changes to the DVT (Developer Tools) service.

Symptoms:

  • Diagnostics show "ready to inject location"
  • Location injection appears to succeed but device location doesn't change
  • No clear error messages in logs

Root Cause: Apple modified the simulate-location service in iOS 18+, causing pymobiledevice3 to fail silently. This is tracked in pymobiledevice3 issue #1387.

Solutions:

Option 1: Downgrade to iOS 17.6 (Recommended)

  1. Download iOS 17.6 IPSW from ipsw.me
  2. Connect device via USB
  3. Open Finder → Select device
  4. Hold Option (⌥) and click "Restore iPhone"
  5. Select downloaded IPSW file
  6. Wait for restore to complete (~15-30 minutes)

Option 2: Debug pymobiledevice3 Directly

# Test location injection with verbose logging
python3 -m pymobiledevice3 --debug developer dvt simulate-location set \
  --tunnel YOUR_DEVICE_UDID -- 35.6762 139.6503

# Check for specific errors:
# - InvalidServiceError: Service not available
# - DeveloperModeError: Developer mode disabled
# - ServiceNotAvailableError: iOS 18+ restriction

Option 3: Check for Updates

# Update pymobiledevice3 to latest version
pip3 install --upgrade pymobiledevice3

# Verify version (check if > 6.1.5 has iOS 18 fixes)
python3 -m pymobiledevice3 version

Detection in App: LocationSpoofer automatically detects iOS 18+ devices and displays:

  • ⚠️ Warning badge in device list
  • Warning banner in main view
  • Pre-injection warning toast
  • Detailed error dialog with recovery steps

Note: This is a limitation of pymobiledevice3/Apple's DVT service, not a bug in LocationSpoofer. Monitor the pymobiledevice3 GitHub for updates.

Debug Logs

View logs in Console.app:

Filter: com.locationspoofer

Or check tunnel logs:

tail -f /tmp/locationspoofer_tunnel.log

🔮 Future Enhancements

See FUTURE_ENHANCEMENTS.md for detailed roadmap.

Planned Features

Priority 1: Multi-Device Support (Est: 26h)

  • Simultaneous spoofing on multiple devices
  • Independent or synchronized modes
  • Per-device rate limiting

Priority 2: CI/CD Integration (Est: 15h)

  • GitHub Actions pipeline
  • Automated testing & code signing
  • DMG packaging & releases

Priority 3: Advanced Route Simulation (Est: 160h)

  • Physics-based movement (acceleration, friction)
  • Behavioral modes (walking, running, driving, cycling)
  • Environmental factors (elevation, terrain, weather)
  • Route recording from real GPS

Additional Ideas:

  • AR Map View (3D terrain visualization)
  • Location History & Favorites
  • Geofencing (stay-within boundaries)
  • Scripting Support (JavaScript/Python automation)
  • Cloud Sync (routes across devices)

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Good First Issues:

  • Add more preset locations
  • Create sample GPX routes
  • UI/UX improvements
  • Performance optimizations
  • Documentation translations

Development Workflow:

  1. Fork the repository
  2. Create feature branch (git checkout -b feature/amazing-feature)
  3. Commit changes (git commit -m 'Add amazing feature')
  4. Push to branch (git push origin feature/amazing-feature)
  5. Open Pull Request

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

📞 Support

⭐ Star History

If you find this project useful, please consider giving it a star! ⭐

Made with ❤️ for iOS developers and testers

About

macOS app to spoof GPS location on iOS devices

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

LocationSpoofer v1.0.0 Latest
Dec 13, 2025

Packages

 
 
 

Contributors

Languages