WLoc changes the location your iPhone reports, and the README says plainly who should and should not do that

What it changes, and what it deliberately refuses to touch

The project's own description is that it is a fully open source, experimental iOS and macOS tool written in Swift, which changes the real reported position of a device by intercepting the requests and responses of the location interface. That is the whole scope, and the README is unusually explicit about where it stops.

The proxy currently handles only two hostnames, the global and the China-region location endpoints, and the file says directly that it should not be treated as a general VPN or a general HTTPS capture tool. That single sentence is the most important line in the document, and it is worth reading as a design constraint rather than a disclaimer. A tool that could see all of your traffic would be a different project with a different risk profile; one that can only rewrite two Apple requests has a much smaller blast radius.

The same honesty shows up in the platform support note. The file states that web-based location works up to a specific iOS 27 beta, and that later betas stopped working because Apple closed the gap. A project that documents the exact version where its technique stopped working is telling you something real about how the technique depends on Apple's implementation rather than on a documented interface.

Two platform paths that converge on one local proxy

The architecture diagram is the fastest way to understand the whole project. You pick a point on a map, the app asks which platform it is on, and the two branches are genuinely different mechanisms that end up in the same place.

On iOS the interception runs inside a network tunnel extension, which is the platform's supported slot for taking over a device's network traffic. On macOS it runs through the system's automatic proxy configuration mechanism instead, pointing the machine at a proxy file served locally. Both branches arrive at the same local HTTPS proxy, and that proxy handles only the two location hostnames and nothing else.

So the design is: map selection in the app, platform routing, one proxy, two domains. There is no attempt here to be a general interception framework, and the narrowness is a feature rather than a limitation, because it is what makes the tool reviewable. You can read the whole data path in a diagram and know exactly what leaves your device and what does not.

No shared signing identity ships with the repository

The certificate step is the part of the build that most projects get wrong, and this one makes the safe choice by default. The repository contains no reusable root certificate private key and no packaged identity file. Every developer has to generate their own certificate on their own machine.

git clone https://github.com/OpenHRTT/wloc.git
cd wloc
pod install

A generation script in the repository root does the work, and it syncs the result into the app and extension resource directories so the build picks it up without manual copying:

chmod +x generate_apple_wloc_p12.sh
./generate_apple_wloc_p12.sh

The default password for the generated identity is a fixed string that matches a configuration constant in the app, and the file is clear that if you change it in the script you must change it in the configuration as well. That coupling is a minor sharp edge, and it is at least documented rather than left to be discovered at runtime.

Four targets, one team, one shared group

After the certificates, the build requires you to change the bundle identifier yourself, with one constraint that is easy to miss: the tunnel's identifier has to be the app's identifier plus a suffix. The file gives a two-line example showing the app identifier and the tunnel identifier derived from it.

The rest is App Group configuration. The group exists for one narrow purpose, letting the iOS app and the tunnel extension share state, and the README tells you to replace the placeholder group string in three specific files: the app entitlements, the tunnel entitlements, and the shared configuration source file. Three files, one string, one value.

The troubleshooting section for signing is short and points at the same thing. All four targets have to be on the correct team, and the app and the tunnel have to be in the same App Group. That is the whole failure mode, and it is the reason the repository also ships a dedicated troubleshooting document rather than folding the diagnosis into the main file.

A URL scheme for importing a location, still marked as unfinished

The file documents an import path that carries an explicit status marker saying the feature is pending development. Locations can be handed to the app through a custom URL scheme, where the payload is URL-encoded JSON carrying a type, a name, a detail string, a latitude, a longitude, and a coordinate system.

The coordinate system field is the interesting part, because it is a list of four values, and three of them are the coordinate systems used by mapping services in different places rather than the one your phone speaks. Alongside the global datum and Apple's own, the list includes two regional datums used by mapping products in China. A tool that lets you state which datum your coordinates are in avoids the class of bug where a location lands a few hundred metres off because the two ends disagreed about the reference point.

Two URL shapes are documented: the encoded JSON directly after the scheme, or the same payload passed as a named parameter. Both are listed as supported. Since the feature is marked as not yet finished, treat the exact shape as something to verify against your build rather than something to depend on.

The tree looks like a shipping app, not a script collection

The repository layout is the first thing worth noting for anyone deciding whether to trust the project. There is an Xcode project and a workspace, a CocoaPods file and a lock file, separate directories for the macOS app, the iOS app, a shared target and a core library, a resources folder, a packaging folder and a tests folder.

A pod file with a committed lock file means dependency versions are pinned, which for an interception tool matters more than it would for an ordinary library, because a moved dependency could change behaviour in ways no test would catch. The presence of a tests directory at all is a signal in a project of this kind.

Around that sit the files you would expect from a maintained open source project rather than a personal script: a changelog, a code of conduct, a contributing guide, a security policy, a licence, a notice file and a third-party notices file. The licence split is worth reading carefully, because the project's own code is under a permissive licence while third-party code is explicitly not covered by it, with the two notice files pointing at the details.

When the override does not take effect, check four things

The troubleshooting section is short enough to summarise, and its four checks are the ones to run in order before digging further.

First, if the build cannot find the identity or certificate files, the answer is to run the generation script from the project root. Second, if signing or the App Group fails, confirm the four targets are on the right team and that the app and tunnel share one group. Third, if you tap the lock control and nothing happens, check that the root certificate is installed and fully trusted; on iOS also confirm the tunnel is connected, and on macOS confirm that the system's automatic proxy configuration actually points at the local proxy file, then refresh the location service as the app instructs.

None of those four checks is exotic, and the fact that they are enumerated rather than left implicit is what a reader needs. A deeper guide lives in the troubleshooting document in the documentation folder.

Editorial conclusion

Before anything else: this changes what your own hardware claims about where it is, and using that against an account you do not own, against an application you do not control, or to misrepresent where you are to another person is not a testing exercise. Several countries regulate location data as personal information and several apps detect spoofed coordinates, so a build you keep for your own regression testing can put you outside the terms of a service you did not write. With that said, the engineering is careful and the scope is unusually narrow: the proxy is built to touch two Apple domains and the README tells you not to treat it as a general VPN or a general capture tool. Clone it, build it, and point it at an app you wrote.

Frequently asked questions

Official sources

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