How Trace works under the hood.
A deep look at the technical foundation and design decisions that power on-device iOS network debugging.
System overview
Trace implements NEPacketTunnelProvider in proxy-only mode, configuring system proxy settings to route HTTP/HTTPS through a local MITM proxy. Three components communicate via a shared App Group container.
Main application
SwiftUI interface for viewing captured traffic, managing filters, and configuring settings. Reads from the shared App Group and provides real-time updates. Handles export, search, replay, modification tools, and utilities.
Network extension (TraceVPN)
Separate process running NEPacketTunnelProvider in proxy-only mode. Configures system proxy settings and runs the local MITM proxy. Handles TLS, HTTP/2, WebSocket, and SSE before writing captures to the App Group.
Widget extension
WidgetKit bundle with standard widget, control widget, and Live Activity. Real-time network statistics and quick actions. Shares data through the App Group container.
Network flow
All captured traffic stays on-device and flows through a local MITM proxy server.
Network extension implementation
NEPacketTunnelProvider
Core component that configures proxy-only VPN network settings via NEProxySettings. Starts the local MITM proxy and applies system proxy rules without routing packets. Runs in a separate process with elevated network privileges.
final class PacketTunnelProvider: NEPacketTunnelProviderCertificate management
On-device certificate authority generates a root CA on first launch. The user installs the root cert via Settings → General → VPN & Device Management. The extension dynamically generates leaf certificates matching intercepted domains. Private keys never leave the device.
Proxy processing pipeline
Proxy configuration
Apply system proxy settings to route HTTP/HTTPS to the local MITM proxy. Start the proxy server and expose it on 127.0.0.1:8888.
HTTP parsing
Handle HTTP/1.1 and HTTP/2 requests and CONNECT tunnels. Track WebSocket upgrades, SSE connections, and request-response pairs.
TLS interception
When the local CA is trusted and MITM is enabled, dynamically generate leaf certificates. Decrypt and re-encrypt HTTPS traffic in the proxy for inspection.
Storage and notifications
Persist captures to the App Group container and notify the main app. Widgets and Live Activities update from shared storage.
Data storage and IPC
App Groups
Shared container enables communication between main app and extension. Both processes can read and write to the shared directory. Used for configuration, captured traffic data, and coordination.
group.com.trace.network-debuggerPersistent storage
Structured storage for captured requests, responses, and configuration. Shared data accessible from app, extension, and widgets. Efficient querying with support for search and presets. Automatic cleanup with configurable retention policy.
Real-time updates
Extension writes new captures to shared storage. Main app observes data changes for live UI updates. Widgets receive notifications for Live Activity updates. Minimal latency between capture and display across all components.
Protocol support
HTTP/HTTPS
Full HTTP/1.1 and HTTP/2 support with complete parsing. HTTPS via TLS MITM with dynamic certificate generation. HTTP/2 stream info with HPACK table viewer.
WebSocket
Detects WebSocket upgrade handshake. Captures and parses individual frames. Distinguishes text and binary frames. Tracks connection lifecycle.
Server-Sent Events
Recognizes SSE Content-Type header. Parses event stream format. Displays individual events with timing. Tracks connection duration.
Limitations
Proxy-only mode captures HTTP/HTTPS for apps that honor system proxy settings. QUIC/HTTP/3 traffic is not captured. Apps that bypass proxy settings will not appear in captures.
Performance considerations
Proxy processing efficiency
Minimal per-connection overhead to maintain network performance. Efficient buffering reduces memory allocations under load. Parsing work is scheduled off the critical path where possible.
Memory management
Extension memory budget is limited by iOS. Aggressive cleanup of processed proxy data. Writes captures to App Group storage as JSON files. Configurable retention policy prevents unbounded growth.
Battery impact
Background processing optimized for power efficiency. Proxy handling path is lightweight. Heavy parsing done asynchronously. Extension can be disabled when not actively debugging.
Security model
On-device only
All traffic capture and analysis happens locally. No data transmission to external servers. No telemetry or analytics collection.
Root certificate trust
TLS interception requires explicit user action to trust root CA. Certificate installation flow clearly explains implications. Users maintain full control over certificate trust.
Data isolation
Captured data stored in app sandbox. No access from other apps without explicit export. Optional encryption for sensitive captured data.
Code transparency
Entire codebase is open source and auditable. No obfuscation or hidden functionality. Build from source to verify binary integrity.
Built with
Modern iOS frameworks and APIs.