Wormholy: shake-to-open network debugging for iOS apps

What Wormholy records, and who it is for

Wormholy targets the moment when an iOS app returns the wrong data and the request itself is the suspect. It records traffic that goes through NSURLSession, then presents requests, responses and headers in a viewer inside the app. The README's pitch is that there is no code to write and no imports, and that HTTPS calls need no certificate work. That second point is the practical difference from a proxy: a proxy sits between the device and the server and usually needs a trusted certificate installed on the device, while Wormholy hooks the session configuration from inside the process. The audience is iOS developers, including those using Alamofire or AFNetworking, since those libraries sit on top of NSURLSession. Swift and Objective-C are both supported.

How the URLProtocol hook and the shake gesture fit together

The mechanism described in the README is URLProtocol injection through session configurations. Wormholy states that it automatically hooks URLSessionConfiguration.default and URLSessionConfiguration.ephemeral, which is why no import is needed at the call site: the session you already create picks up the recorder. Captured exchanges are stored and shown in a viewer that opens on a shake gesture, and the same viewer exposes filtering, request stats such as HTTP method breakdown, status code distribution, error types and response size, plus export as a Postman collection and as cURL. Two boundaries are documented. Background sessions cannot be instrumented, because Apple does not support custom URLProtocol classes with background URLSessionConfiguration. And the hook is per configuration instance: if you want different behaviour for one session, you call the session-specific enable or disable before creating the URLSession, not after.

Installing Wormholy and capturing your first request

The README recommends installing Wormholy only in debug mode and removing it before sending an app to production, and gives a CocoaPods line that scopes it to the Debug configuration. Swift Package Manager is also supported. The first block below is that recommended install form.

pod 'Wormholy', :configurations => ['Debug']

With the pod in place, the README says you run the app and shake the device or simulator. No import and no call site change is required, because the default and ephemeral session configurations are hooked automatically. If you want to change what gets recorded, the configuration is plain property assignment, as in this example adapted from the README's configureWormholy function.

func configureWormholy() {
  Wormholy.ignoredHosts = ["example.com", "analytics.internal"]
  Wormholy.limit = 200
  Wormholy.defaultFilter = "status:500"
  Wormholy.shakeEnabled = true
  Wormholy.setEnabled(true)
}

Here ignoredHosts excludes hosts from recording, limit caps how many logs are retained, and defaultFilter pre-fills the search box. The README notes that ignoredHosts matches on host suffix, so ignoring example.com also ignores api.example.com. If you would rather not shake, the README documents the environment variable WORMHOLY_SHAKE_ENABLED set to NO, and a manual trigger by posting the wormholy_fire notification.

NotificationCenter.default.post(name: NSNotification.Name(rawValue: "wormholy_fire"), object: nil)

To wipe captured traffic, the README documents Wormholy.clearRequests with a completion handler called on the main actor, and the Objective-C name clearRequestsWithCompletion:.

Background sessions and the iOS 16 floor are the real limits

The clearest failure mode is stated by the project itself: background URLSessionConfiguration cannot be instrumented, because Apple does not support custom URLProtocol classes there. If your app downloads through a background session, Wormholy will show nothing for that traffic, and no configuration flag changes it. The second limit is the platform floor. The README lists iOS 16.0+ and points anyone who needs an older version to the 1.7.x releases, so a project pinned to an earlier deployment target either stays on that older line or goes without. There is also a memory dimension: the README describes Wormholy.limit as existing to manage memory usage, which implies that an unlimited capture of large responses is not the intended mode. And the production warning is not decorative. A library that records request and response bodies is a data exposure risk if it ships, which is why the README's own instruction is to remove it before release.

Wormholy compared with a proxy such as Charles

Charles is the comparison the project's own topics invite, and the difference is where the interception happens. A proxy is external: the device or simulator points at a host on your network, and every app on that device can be observed. That makes it useful for traffic your code does not own, but it requires certificate setup for HTTPS and a running host. Wormholy is in-process: it hooks session configurations inside one app, so HTTPS needs no certificate work and there is no second machine involved, but it only sees NSURLSession traffic in the build where it is installed. The trade is scope for setup. A proxy also survives the case Wormholy cannot cover, the background session, because it never touches URLProtocol. DebugSwift appears in the same search space as another in-app debugging option; the README does not describe its internals, so the honest comparison stops at the fact that both are in-app tools.

Maintenance, licence and the cost of upgrading

The repository is not archived and the last push was on 2026-09-17, which is recent enough that the project is being touched. Releases are not on a strict cadence: 2.4.0 and 1.8.0 both landed on 2026-03-21, and 2.3.0 on 2026-01-18. The presence of both a 1.8.0 and a 2.x line in the same window matches the README's note that older iOS versions should use 1.7.x, so the older line is still being published rather than abandoned. The upgrade cost is mostly the platform floor: moving from 1.7.x to 2.x means moving to iOS 16.0+, and any team that cannot do that stays on the older line and does not receive the newer features the README lists, such as request stats. The licence is MIT, which is permissive and places few obligations beyond keeping the notice; this is a description of the licence text, not legal advice, and teams with specific concerns should read the LICENSE file in the repository.

Editorial conclusion

Reach for Wormholy when you need to see what an iOS build is actually sending, including through Alamofire or AFNetworking, and you want that without writing intercepting code. Skip it if you need to inspect background sessions (the README states Apple does not support custom URLProtocol classes there), if you target iOS below 16.0 and cannot stay on the 1.7.x line, or if you need traffic from a simulator process you cannot shake. Before adopting, verify the iOS 16.0 minimum against your deployment target, confirm that installing with the Debug-only CocoaPods configuration actually keeps the library out of your release build, and check whether your team already has a proxy-based workflow that would make a second capture path redundant.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. pmusolino/Wormholy on GitHub
4. README
5. Releases