Set up Geovoya

Install and open Geovoya

Get the installer for your computer from the download page, which also lists the SHA-256 of every file so you can check what you downloaded. On a Mac, Apple menu → About This Mac tells you whether you have an Apple chip or an Intel processor; on Windows, look under Settings → System → About → System type. Windows on ARM and Linux are not release targets.

The installer includes ADB, the iPhone runtime and the Android location helper. You do not need Node.js, Python, Xcode, Android Studio or an Appium server to use Geovoya.

What you need

Use one unlocked phone and a USB cable that carries data — a cable that only charges will not do, and charging alone does not prove a data connection. Keep the computer online for the first preparation.

• iPhone XS / XR or newer on iOS 17.4 or later. iOS 17.0–17.3 cannot be supported; Geovoya shows Update iOS with a link to Apple’s update instructions.
• Company-managed iPhones (MDM or supervised) may block Developer Mode. If the switch never appears, ask your IT administrator.
• Windows needs Apple Devices from the Microsoft Store for Apple’s USB services.
• Android 8 and later, with USB debugging. Cable-free Wi-Fi pairing needs Android 11 or later.
• A new major iOS version can need a Geovoya update before it works.

First launch

On first launch, choose your computer and phone, work through the matching checklist, and select Continue to map. Setup in the toolbar opens the checklist again at any time.

For iPhone the checklist is live: each step ticks itself off as the connected phone completes it, and Continue to map unlocks once the phone reaches Ready (you can also Skip for now). For Android the checklist is guidance, and the phone still has to show Ready before a location session can start.

iPhone setup

The iPhone needs a one-time setup, and Geovoya does most of it. There is no “Prepare” button to hunt for: the Phone card and the Setup checklist always show the current step.

On a Mac

1. Plug in and unlock. Connect the iPhone with a USB data cable and unlock it. The card reads Unlock iPhone until you do.
2. Tap Trust. Geovoya asks the phone to trust this Mac, so the Trust This Computer? prompt appears by itself. Tap Trust and enter your passcode on the phone.
3. Show Developer Mode. When the card reads Developer Mode is off, click Show Developer Mode. This makes the hidden switch appear on the iPhone — Xcode is not required — and Geovoya then shows what to do on the phone.
4. Turn it on and restart. On the iPhone, close and reopen Settings, open Settings → Privacy & Security → Developer Mode, turn it on and restart when asked. After the restart, unlock the phone, tap Turn On and enter your passcode. Apple documents the switch under enabling Developer Mode on a device.
5. Geovoya gets the phone ready. Keep the cable connected. While the card reads Getting ready…, Geovoya mounts Apple’s developer support image automatically; that needs internet for a few seconds. It happens again by itself after every iPhone restart. If it fails, Geovoya retries on its own and Retry tries again immediately. Continue once the phone shows Ready.
6. Optional: use Wi-Fi. Choose Set up Wi-Fi in the checklist, or Connection: USB · Change, so the cable is only needed this once. See connect over Wi-Fi.

On Windows

1. Install Apple Devices. Install or update Apple Devices from the Microsoft Store and open it once, so Windows loads Apple’s USB services. Apple explains connecting and trusting a PC.
2. Plug in and unlock. Connect the iPhone with a USB data cable and unlock it. The checklist ticks this step once Geovoya sees the phone.
3. Tap Trust. The Trust This Computer? prompt appears automatically. Tap Trust on the iPhone and enter your passcode — and approve on the PC as well if Apple Devices asks.
4. Show Developer Mode. Click Show Developer Mode on the Phone card or in the checklist. The switch is hidden on phones that have never been connected to Xcode; this reveals it.
5. Turn it on and restart. On the iPhone, close and reopen Settings, enable Settings → Privacy & Security → Developer Mode, restart, then tap Turn On and enter your passcode.
6. Geovoya gets the phone ready. Keep the cable connected and the PC online for a few seconds while the card reads Getting ready…. This repeats automatically after every iPhone restart. Wait for Ready.
7. Optional: use Wi-Fi, so the cable is only needed once.

If Geovoya reports Apple USB services are unavailable, repair Apple’s device-support installation and reconnect. The upstream iPhone library also documents the Windows USB service prerequisite in its Windows notes. Do not install USB drivers from random download sites.

Android setup

On a Mac

1. On the phone, open Settings → About phone, find Build number and tap it seven times. Some phones keep it under Software information. Enter your screen lock if asked.
2. Open Developer options and enable USB debugging. Menu locations vary by manufacturer; Android’s developer settings cover the details.
3. Connect and unlock the phone, then approve Allow USB debugging? for your computer. A separate Mac USB driver is normally unnecessary.
4. In Geovoya, select the phone and click Prepare. This installs Appium Settings, grants its location permissions and selects it as the mock-location provider.
5. If Android wants a manual choice, open Developer options → Select mock location app → Appium Settings. Keep Android Location switched on and allow the helper’s location access. Return to Geovoya and wait for Ready.

On Windows

1. Enable Developer options and USB debugging exactly as above.
2. Connect and unlock the phone, and accept its USB debugging authorisation prompt.
3. If Windows cannot find the phone, install your manufacturer’s ADB USB driver from Android’s OEM driver list. Reconnect, and try a direct USB port with a data cable.
4. Select the phone in Geovoya and click Prepare. Approve the helper’s permissions, and pick Appium Settings under Select mock location app if prompted.
5. Wait for Ready before setting a location.

Pro, your account and cloud sync

The free plan needs no account at all. Geovoya Pro — faster and slower speeds, multi-stop routes, the Walk tab, realistic movement, GPX/KML import and export, the full route library with map editing, and up to three phones at once — needs a Geovoya account with a subscription.

1. Click Sign in in the Geovoya toolbar. Once signed in, that button shows your email address.
2. Geovoya opens geovoya.com/activate in your browser and shows a short code.
3. Sign in there and confirm the code matches. The app switches to Pro by itself; there is nothing to paste back.

Sign in on every computer you use. Pro keeps working offline; after a long stretch without a connection, open Geovoya while online so it can refresh. If Pro controls still show a Pro badge after signing in, check Account for the plan and the last refresh time.

Set your first location

1. Choose Fixed location. Search for a place and pick a result, click the map, or type a latitude and longitude and select the coordinates.
2. Check the selected phone and point. Selecting a pin only changes the preview.
3. Click Set location. For another point, select it and click Update location.
4. Open a map app on the phone, allow its location permission, and press its current-location button. Confirm the phone shows the area you chose.
5. Click Restore real location when you are finished, and give the phone’s map a moment to refresh before unplugging.

Geovoya shows command acknowledgements on iPhone and helper readbacks on Android. Those confirm the connection; they are not independent proof of what another app consumed. Some apps reject or cache simulated locations.

Follow a road route

1. Select Route. Search or drop a pin for the start, then click Add selected pin to route. Add a destination the same way.
2. With Pro you can add up to 12 stops, reorder them, loop back to the start and pause at each stop.
3. Click Plan road route and inspect the line and distance before starting. Pins snap to a road within 1 km; stops that no road joins fail planning instead of drawing a straight line.
4. With Pro you can reshape the line: click it to add a via point and drag it, drag the numbered stops, or use Freehand segment for straight lines. Snap to roads re-plans only the part you changed. Editing is off while a route runs or is paused.
5. Choose a Speed — 45 mph on the free plan, any preset or 1–120 mph with Pro — and click Start route. Geovoya sends a new target every second, and you can change the speed while it runs.
6. Pause route holds the current point and Resume route continues. Arrival holds the destination.

With Pro, Import GPX/KML loads a recorded track as a route or a waypoint list as stops, and Export GPX saves the planned route and your saved places.

The speed is constant, whatever the road limit or traffic. Keep Geovoya running, the cable connected and the computer awake; minimising the window does not stop playback, but unplugging, sleep or slow updates pause it. Reconnect the same phone and press Resume. Restarting Geovoya does not recover route geometry.

Walk around (Pro)

1. Select Walk, choose a starting point and click Set location.
2. Choose a speed such as Walk · 3 mph, or press [ and ] to step through the presets.
3. Drag the joystick, or hold W A S D or the arrow keys. Hold Shift for twice the speed, or Alt (Option on a Mac) for half. The keys also work from the Fixed and Route tabs.
4. Let go, or press Esc, to stop. Walking also stops when the window loses focus, and on disconnect, sleep or Restore real location.
5. Press ? for every shortcut. If you prefer only Ctrl/⌘ shortcuts, turn off Settings → Keyboard → Enable single-key shortcuts.
6. Turn on Realistic GPS for small position jitter and speed variation.

Connect over Wi-Fi

Once a phone works over USB, Geovoya offers Switch to Wi-Fi if your computer has an active Wi-Fi connection. Stay on USB dismisses the offer for that phone, and Connection: USB · Change below the Phone card brings it back.

Keep both devices on the same ordinary network and leave USB connected until Geovoya confirms the switch. It re-checks the same phone over Wi-Fi, carries the current location across and resumes a running route from its held point. If the Wi-Fi session fails, Geovoya tries to recover over USB; if both fail it keeps the session unresolved so you can Retry or Restore. Going back from Wi-Fi to USB still needs a Restore first.

iPhone, on Mac or Windows

1. Connect by USB once and finish the one-time setup above until the iPhone shows Ready. Windows still needs Apple Devices.
2. Select the iPhone and click Switch to Wi-Fi in the offer or the connection panel. Geovoya saves the pairing record locally and enables Apple’s wireless connection setting.
3. Wait for Connected over Wi-Fi. You can unplug the USB cable. before unplugging anything.
4. Close the panel and wait for Ready — Geovoya still prepares the phone by itself, including after a restart — then set a location or start a route as usual.

If the iPhone does not appear, reconnect USB and enable Show this iPhone when on Wi-Fi in Finder (Mac) or Show this device when on Wi-Fi in Apple Devices (Windows), then Apply. Unlock the phone and refresh Geovoya. First-time trust always needs a cable: this is not wireless pairing with an untrusted phone. iOS 17.4+ is required — the upstream project documents the transport in its iOS 17 tunnel guide.

Android, on Mac or Windows

Already connected over USB (Android 8+). Prepare the phone normally, put it on the same Wi-Fi network, then click Switch to Wi-Fi. Geovoya reads the phone’s Wi-Fi address, enables ADB TCP/IP on port 5555 and verifies the hardware identity before moving the session across. Use a network you trust; restarting the phone turns this network-debugging mode off again. This is Android’s USB-assisted Wi-Fi flow.

Without a cable (Android 11+). Open Manual setup and troubleshooting in the connection panel.

1. Enable Developer options by tapping Build number seven times, then turn on Wireless debugging while on the same Wi-Fi as your computer.
2. In Geovoya’s connection panel choose Wi-Fi, then Android.
3. On the phone, open Pair device with pairing code. Enter its IP address, pairing port and six-digit code in Geovoya and click Pair phone. Geovoya does not save the code.
4. Go back to the phone’s main Wireless debugging screen and enter that screen’s IP address and connection port in Geovoya, then click Connect paired phone. The connection port is not the pairing port.
5. Close the panel, select the phone and click Prepare if needed. Keep Location on and Appium Settings selected as the mock location app.

If the connection drops, check Wireless debugging and reconnect with its current address and port; ADB may also reconnect through local discovery. Geovoya checks the phone’s hardware serial, so a changed port is still the same phone. Android’s own wireless debugging guide has the command-line equivalents.

Allow Geovoya and its bundled device tools through local-network and firewall prompts. Guest networks, client isolation and VPNs can block local discovery. Wi-Fi has automated adapter, transport, pairing, identity, refresh and interface coverage, but it has not yet been verified end to end on physical phones on either host OS.

If something goes wrong

Still stuck?

Email [email protected] — what to include is on the FAQ, and it is the fastest way to a real answer. The FAQ covers plans, privacy and supported hardware, and the open source page has the source archive if you would rather read the code.

Tested so far: installers are built and checked on macOS 15 and Windows Server 2025. Mac to iPhone over USB worked on a physical phone during validation of Ghost 0.1.7, the version Geovoya is based on. Windows setups, Mac to Android and Wi-Fi mode have automated coverage but have not all been verified on physical phones. Geovoya has no telemetry or analytics: device identifiers, saved places and the recovery record stay on your computer.