OpenHRTT WLoc: an open source Apple location spoofer that proxies gs-loc.apple.com

What WLoc actually changes, and who needs that

Apple devices ask gs-loc.apple.com for location data. WLoc sits between the device and that host and returns a different answer. The README states the goal plainly: changing the response of the gs-loc interface to change the device's real position. Nothing else on the device is touched. That narrowness is the whole design.

The audience is Apple platform developers and testers. Someone building a location-aware app needs to see how it behaves at a specific coordinate, and a simulator gives you limited control over that. A QA engineer checking whether a store-locator screen picks the right region has the same problem. WLoc gives both a way to pin a coordinate and hold it there.

The repository topics list apple-simulator-location, mac-simulator-location and simulator-location, which matches that reading. The project also advertises a web path at wloc8.com and says iOS supports 5G and Wi-Fi, which is a different deployment shape from a simulator-only tool. Treat the web path as the hosted variant and the repository as the self-built one.

The proxy path: Packet Tunnel on iOS, PAC on macOS

The README carries a Mermaid flowchart that describes the data flow. A user picks a location on a map. The flow then branches by platform. On iOS it goes through a Packet Tunnel Extension; on macOS it goes through the system PAC. Both branches converge on a local HTTPS proxy. The proxy handles only the target location domains.

The README names those domains: gs-loc.apple.com and gs-loc-cn.apple.com. It then states that the proxy should not be treated as a general VPN or a general HTTPS capture tool. That sentence is doing real work. A Packet Tunnel Extension on iOS normally implies a full tunnel, but here the scope is one or two hostnames, and the macOS side is a proxy auto-config file rather than a tunnel at all.

The practical consequence is that the two platforms fail differently. On iOS, the failure mode is a VPN that never connects or a tunnel that connects but does not intercept. On macOS, the failure mode is a PAC file that points somewhere other than the local proxy. The README's own troubleshooting entry splits along exactly those lines: iOS needs the VPN connected, macOS needs automatic proxy configuration pointed at the local PAC, followed by a refresh of location services as the app prompts.

Building WLoc from source: clone, pod install, generate a certificate

The README gives a three-step quick start. First, clone the repository and install CocoaPods dependencies from the Podfile at the repository root.

# Clone the repository
git clone https://github.com/OpenHRTT/wloc.git

# Install dependencies
cd wloc
pod install

The repository ships a Podfile and a Podfile.lock, so pod install is the expected dependency step. After that you open the workspace, not the project file.

The second step is certificate generation. The README is explicit that the repository contains no reusable root certificate private key and no .p12 file, and that every developer must generate an independent certificate locally. The script is at the repository root and needs the executable bit.

chmod +x generate_apple_wloc_p12.sh
./generate_apple_wloc_p12.sh

According to the README, the script generates the certificate and syncs it into the App and Extension resource directories. The default .p12 password is app-wloc, which matches the AppWLocConfig.proxyIdentityPassword value. If you change the password in the script, the README says you must change the app configuration to match. That coupling is easy to miss and will surface as a build or handshake failure rather than a clear error.

The third step is identity. Change the Bundle Identifier, and keep the Tunnel identifier as the app identifier plus .tunnel. The README gives com.example.wloc and com.example.wloc.tunnel as the pattern. The App Group is used only for sharing state between the iOS main app and the Tunnel, and the README lists three files where group.com.wlocapp.shared must be replaced with your own group: Resources/iOS/WLocApp-iOS.entitlements, Resources/Tunnel/WLocTunnel-iOS.entitlements, and WLocApp/WLocCore/AppWLocConfig.swift. Missing one of the three produces a signing or entitlement error, which the README lists as a known symptom.

One build detail worth flagging: running the WLocApp-macOS scheme in Debug installs the signed app to /Applications/WLoc8.com.app and launches it from there. The README notes the current Xcode user needs write permission on /Applications. If you only want to build, set WLOC_SKIP_DEBUG_INSTALL=1 in the environment.

Importing a location through the wlocapp:// URL scheme

The README marks external links as still under development, but the payload format is documented. The app accepts a wlocapp:// URL whose payload is URL-encoded JSON. The JSON has a type of location and a data object with name, detail, latitude, longitude and coordinateSystem fields.

{
  "type": "location",
  "data": {
    "name": "Tiananmen Square",
    "detail": "Beijing",
    "latitude": 39.9087,
    "longitude": 116.3975,
    "coordinateSystem": "wgs84"
  }
}

The README lists four accepted coordinateSystem values: wgs84, gcj02, bd09 and apple. That matters if you are feeding coordinates from a Chinese map provider, because gcj02 and bd09 are offset systems and passing them as wgs84 will put you in the wrong place. The full URL can take either form, wlocapp://<percent-encoded-json> or wlocapp://?payload=<percent-encoded-json>. The README does not document what happens when the payload is malformed, so validate before you hand a URL to the app.

Where WLoc stops being the right tool

The README itself draws the first boundary: this is not a general VPN and not a general HTTPS capture tool. If you need to inspect arbitrary traffic from an iOS device, WLoc will not do it, and trying to stretch it that way will not work because the proxy only handles the target location domains.

The second boundary is version support on the web path. The README states that web location works up to iOS 27.0 beta5, and that versions after 27.0 beta6 cannot be used because Apple has blocked the approach. That is a hard ceiling stated by the project, not a soft caveat. Anyone planning around the web path should check their target iOS version against that sentence before committing.

The third is the trust requirement. The troubleshooting section says a lock that does not take effect usually means the root certificate is not installed and fully trusted. Installing a root CA on a device is a real security decision, not a build step. On a personal test device that is your call. On a managed or shared device it is someone else's, and the certificate you generate is per-developer by design, which means it does not travel well across a team without repeating the setup.

Finally, the project is macOS and iOS only. There is no Linux or Windows path in the repository layout, and no server component you could run headless.

How WLoc differs from a general proxy tool

A general HTTPS interception proxy such as mitmproxy takes the opposite approach. You install its certificate, point the device at it, and then you write rules for whatever hosts you care about. It is host-agnostic by default and you narrow it down. WLoc is host-specific by default and does not widen.

That difference shows up in the setup cost and in the failure modes. With a general proxy you spend your time on rules and on certificate trust across many clients. With WLoc you spend it on Xcode signing, an App Group shared across three files, and a Packet Tunnel extension. The payoff is that once it builds, there is no rule authoring: the gs-loc domains are already the target, and the map UI is the interface.

The other real alternative is the simulator's own location controls in Xcode. Those are simpler and need no certificate, but they are tied to the simulator. The README's framing, with a Packet Tunnel Extension on iOS and a system PAC on macOS, is aimed at physical devices as well, which is the gap a simulator control does not fill. If your testing never leaves the simulator, WLoc is more machinery than you need.

Licence, third-party code and what upgrading costs

The project's own code is MIT licensed, per the LICENSE file at the repository root. The README adds a qualification that matters more than the headline: third-party code is not covered by that MIT licence, and the details are in NOTICE and THIRD_PARTY_NOTICES.md. If you plan to redistribute a build, read those two files rather than assuming the MIT label covers the whole binary. This is a description of what the repository states, not legal advice.

On maintenance, the repository is not archived, and the last push was on 2026-09-15. The most recent release is v1.1 from 2026-08-04, following v1.0 on 2026-07-23. A CHANGELOG.md sits at the repository root, which is where release-to-release changes are recorded.

Upgrade cost is dominated by the certificate and identity setup rather than by code. Because the repository ships no reusable .p12, a fresh clone means running generate_apple_wloc_p12.sh again, and any local edits to the Bundle Identifier or App Group are yours to reapply. The default password app-wloc is tied to AppWLocConfig.proxyIdentityPassword, so a password change is a two-file change. Expect the first build on a new machine to cost more than subsequent ones.

Editorial conclusion

Adopt WLoc if you are an Apple developer or QA engineer who needs to move a simulator or a physical device to a fixed coordinate and can build a signed Xcode project with a Packet Tunnel extension. Do not adopt it if you want a general-purpose VPN, a traffic capture tool, or anything that works without a trusted root certificate on the device. Before building, confirm three things: that your Xcode user can write to /Applications or that you set WLOC_SKIP_DEBUG_INSTALL=1, that you have replaced group.com.wlocapp.shared in all three listed files with your own App Group, and that the iOS version you are targeting still falls inside the range the README claims for the web path.

Frequently asked questions

Official sources

1. License: MIT
2. OpenHRTT/wloc on GitHub
3. Project website
4. README
5. Releases