WLOC community edition: spoofing iOS location through a proxy module

The chain, and the piece that breaks on iOS 27

WLOC is a location modification tool for Apple devices that works by intercepting network location responses rather than by touching the GPS hardware. The repository is the community-maintained edition, restored from the original Yu9191 project, and it keeps the upstream author's history and licence. The restore baseline is commit 529fcd8 from 2026-09-04, and the README is explicit that it is not the original author's official repository and that it cannot modify hardware GPS positioning.

The mechanism is a chain of five things. The proxy client module intercepts the traffic, the MITM and HTTPS decryption capability of that client unwraps it, a trusted CA certificate makes the interception legitimate to the system, a map page and a Shortcut supply the coordinates, and the Apple network location request then returns the target coordinates. The README draws exactly this chain and makes the point that missing any single element produces one of the classic symptoms: the page opens but nothing saves, the Shortcut request fails, or the save succeeds and the map does not move.

The limitation is at the front of the document and it dominates everything else. From iOS 27 beta 6 onwards, upstream has hit TLS and MITM restrictions related to WLOC, because the traditional approach depends on the proxy client decrypting Apple's HTTPS location requests. The maintainer therefore treats iOS 27 release and release candidate builds as unsupported, and the warning is aimed at people who are reinstalling the module, the certificate and the Shortcut repeatedly, because the errors they are seeing, a Shortcut that reports a broken connection, a saved location that does not change, do not mean the installation was done wrong.

So this is a tool with a hard operating envelope, and the envelope narrows over time.

Picking a point, and the two ways to hand it over

The coordinates come from a web page, and the project hosts one at a workers.dev address, with a link to deploy your own copy to Cloudflare Workers.

Method A is the page itself. You open it, choose a point on the map, search for a place, type coordinates, or paste a map share link, and then press the button that stores the location to the device. The flow diagram shows what happens: the page requests a save, the WLOC module on the device intercepts that request, and the target coordinates are written. The important caveat is that Safari must be going through the proxy client that has WLOC enabled, and a page that says it succeeded only means the save chain completed, not that the system position has changed.

Method B goes through Apple Maps. You pick a place in Apple Maps, long-press to drop a pin, open the place card, use the share control, and choose the WLOC Shortcut from the system share sheet. The Shortcut parses the shared link into coordinates and saves them to WLOC. If the Shortcut is missing from the share menu, the documented fix is to open the Shortcuts app, run the WLOC Shortcut once by hand so the system permission prompts are answered, and then check again under more in the share menu.

A third path, using Amap, works the same way through the system share sheet, and the README warns against copying only the place name, because the Shortcut needs the URL or text that the map share produces in order to hand it to the parse service.

The Shortcut points at a parse endpoint, currently:

https://wloc.xepesw.workers.dev/api/parse

The maintainer states that the parse chain of the current Shortcut has been tested on a real device, and immediately qualifies that this only shows the Shortcut parsing works, not that iOS 27 supports the traditional WLOC flow. A separate note says installed older Shortcuts do not update themselves, so a stale Shortcut can produce errors, and points to a migration document in docs/.

Refreshing the location, in an order that matters

The part of the flow that looks fussy is the part that actually determines whether the spoof takes effect, and the README is explicit that the order is not a suggestion.

The Shortcut jumps to the location services page after saving the coordinates. From there you turn the location service off, turn on airplane mode, and then confirm that Wi-Fi and Bluetooth are also off, because iOS can preserve a manually enabled radio state, so the airplane mode icon alone is not proof. You wait about ten seconds in that state, turn airplane mode off, wait for the network and the VPN or proxy to come back, confirm the proxy client has reconnected and the WLOC module is still enabled, and only then turn the location service back on and check the map.

The reasoning is in the documentation. If you turn location on before the VPN or proxy has recovered, the system can obtain a positioning result that never passed through the WLOC environment, and the whole operation silently does nothing. The recommended order is repeated in bold in the warning block: location off, airplane mode on, confirm Wi-Fi and Bluetooth off, wait ten seconds, airplane mode off, wait for the network and VPN, and only then location back on.

This step is also the one that cannot bypass the iOS 27 restriction, and the README says so directly. Verification is a short list as well: confirm the VPN or proxy is connected, confirm the WLOC module is still enabled, confirm the location service is back on, then fully quit Apple Maps, reopen it and wait a few seconds to see where the blue dot lands.

The module per proxy client, and the certificate trap

The project publishes a module for each of the supported proxy clients, and each is a raw URL you import. The subscription table gives the Surge and Egern module, the Quantumult X configuration, the Loon plugin, the Stash override and the Shadowrocket module, each pointing at a file under the modules/ directory of the repository.

Egern follows the upstream Surge compatibility instructions and has not been separately reviewed by the maintainer, and Stash uses its native override format. The Stash entry is a plain .stoverride file rather than a module, which is worth knowing before you look for a module that does not exist for that client.

The installation path per client is a set of menu clicks, and the paths differ enough that the README spells them out: for Loon it is configuration, plugins, add, add URL, paste the wloc.lpx address and install, then turn the plugin on. For Shadowrocket it is configuration or modules, add module, URL, paste the wloc.module address, save and enable. For Surge it is modules, install new module, install from URL, paste the wloc.sgmodule address and enable. Quantumult X, Stash and Egern work the same way through their module, rewrite or override pages.

Then comes the certificate, and the warning is emphatic: a module showing as installed does not mean WLOC works. MITM and HTTPS decryption must be enabled and the CA certificate generated by the proxy client must be installed and fully trusted.

The Apple location requests that need intercepting are named explicitly, gs-loc.apple.com, gs-loc-cn.apple.com and gsp-ssl.ls.apple.com, which is why MITM has to be on. The CA is generated in the proxy client's certificate settings and installed, then the profile is installed from the VPN and device management page in iOS settings. The step people miss is the third one, and the README calls it the easiest to miss: opening the certificate trust settings and enabling full trust for the root certificate. Installing a profile is not the same as trusting the certificate, and the symptoms of skipping it are a Shortcut reporting a broken network connection, a failed request, a certificate error in Safari or on the location request, and a coordinate change with no effect.

The code behind the pages, and how to run your own

The repository is a JavaScript project with a Node 22 requirement, and the manifest is small enough to read in one go. The package is private and named wloc-community, it is an ES module, the licence is AGPL-3.0, and the scripts show what the project does with itself: configure runs a configuration script, check runs a check script with a release variant, test runs the Node test runner over the worker tests, and there are build and pages build scripts delegated to the worker directory.

The layout matches that. There is a modules/ directory for the per-client module files, a worker/ directory for the Cloudflare Worker, a dist/ directory, templates/, scripts/, docs/, a SECURITY.md, a NOTICE.md and a CHANGELOG.md. The manifest is:

{
  "name": "wloc-community",
  "private": true,
  "type": "module",
  "license": "AGPL-3.0",
  "engines": {
    "node": ">=22"
  },
  "scripts": {
    "configure": "node scripts/configure.mjs",
    "check": "node scripts/check.mjs",
    "check:release": "node scripts/check.mjs --release",
    "test": "node --test worker/test/*.test.mjs worker/test/*.test.js",
    "build:check": "npm --prefix worker run build:check",
    "pages:build": "npm --prefix worker run pages:build"
  }
}

Running your own Worker is a supported path rather than a workaround, and the project links a deploy link aimed at Cloudflare Workers. That matters for two reasons. It removes a third party from the path of your coordinate data, and it means the parse endpoint your Shortcut calls is one you control, so the chain does not break when somebody else's deployment changes.

The licence is AGPL-3.0, which is the same terms the upstream project carried and which the community edition preserves, with the upstream author and contributor records kept in the branch history. The repository has no GitHub releases and the last push was on 2026-09-18.

Where WLOC is the wrong tool

The first limitation is the version ceiling, and it is not a soft one. On iOS 27 release and release candidate builds the technique does not work, and the maintainer asks you to stop reinstalling things. Any plan that depends on WLOC has to assume the platform will keep pulling the rug, because the direction of travel is clear: the vendor is closing the MITM path, and this project lives in the gap.

The second limitation is what it does not do. It cannot modify hardware GPS positioning, so a system that uses the GPS fix directly rather than the network location response is unaffected, and the README says so plainly. It also requires a trusted root certificate and a network interception on the device, which on a phone you own is a configuration decision and on a phone you do not own is a different kind of problem entirely.

The third limitation is the fragility of the chain. MITM on, CA installed and trusted, module enabled, Shortcut up to date, coordinates parsed, then a strict refresh order, and any one of those failing produces an error message that points at the wrong thing. The README repeatedly warns that symptoms like a saved location that does not change do not mean the installation was wrong, which is an admission that the feedback loop here is poor.

There is also a question of what the tool is for. If you are testing an application that behaves differently by region, WLOC is a direct answer. If you are trying to appear somewhere you are not for access control reasons, the same chain is being used for a purpose the tool was not designed around, and the platform is closing the door for exactly the class of use that most attracts abuse.

The real alternative for testing is a simulator, and the difference in approach is fundamental. Xcode's location simulation and the simulator's location features set the position the operating system reports, without any certificate, any interception and any refresh ritual, and they work on the current iOS version because they are inside the platform rather than outside it. WLOC exists for the case the simulator cannot cover, which is a real device on a real network, and there the interception approach is the only one available. If you can test in a simulator, do that, because it removes six fragile steps and an unsupported-version cliff.

Editorial conclusion

Adopt the WLOC community edition if you need to test an iOS application against a chosen location and you are on an iOS version that still permits the TLS interception the technique depends on, and if you are willing to install a trusted root certificate and a Shortcut on a device you control. Do not adopt it on iOS 27 release or release candidate builds, because the maintainer treats those as unsupported and warns that repeated reinstalls will not help, and do not adopt it if you need to change the hardware GPS fix, which this approach cannot do. Before you start, check your iOS version against the table in the README, and if you do proceed, set up your own Worker and point the Shortcut at your own parse endpoint rather than relying on the shared one.

Frequently asked questions

Official sources

1. Issues
2. License: AGPL-3.0
3. README
4. xepes0/wloc on GitHub