Trace documentation

Trace is an on-device iOS network debugger that captures HTTP(S), WebSocket, and SSE traffic using a Network Extension packet tunnel. It runs a local MITM proxy, stores captures in an App Group container, and ships tools for inspection, modification, replay, and export. These docs cover how to use Trace and how to work on the codebase.

Who this is for

Developers debugging network behavior on iOS
QA and release engineers validating regressions or backend changes
Contributors working on the Trace app or extension

How the docs are organized

Start Here: install Trace and capture your first requests
Use Trace: inspect, filter, and export sessions
Advanced Usage: deeper capture modes and customization
Developers & Contributing: architecture, building, and APIs

What you will learn

How to install and trust the Trace root CA for HTTPS inspection
How capture modes differ and what they include
How to inspect, filter, and export traffic
How the system is built (app, extension, SwiftPM modules)

Get started in 2 minutes

Prerequisites:

iOS 16.0 or later
A physical iPhone or iPad (Network Extension packet tunnels do not run in the simulator)

Start capturing:

Open Trace and complete onboarding (VPN permission, optional certificate trust).
Go to Network and tap Start Capture.
Use any app and watch requests appear.

Tip

New here? Follow the Quick Start for a guided walkthrough.

Key concepts

Proxy-only capture: Uses system proxy settings and captures apps that honor proxy settings.
Full-tunnel capture: Routes all traffic through the tunnel and forwards via a SOCKS5 server (advanced).
On-device MITM: A local root CA enables HTTPS inspection when trusted.
Shared storage: Captures, sessions, and config are stored in an App Group container.