See every request your iOS app makes, and every file it keeps, from inside the app.
Cerebro is a debug-only inspector that lives in your app. Add the package, call Cerebro.start(), and a floating button opens a dashboard with everything your app sent and received, live, with no proxy, no certificates and no Mac.
- Every kind of traffic:
URLSession, includingURLSession.sharedand background sessions,URLSessionWebSocketTask,NWConnection, and Server-Sent Events as they stream in. - Readable payloads: pretty JSON, gzip unpacked, and protobuf decoded to JSON from rules you write once.
- Your app's files: the Files tab browses, previews, shares and changes what your app keeps on disk.
- Answers, not just logs: timings, sizes, connection details, System Info, and previous sessions that survive a crash.
- Easy to share: a request as cURL or JSON, or the whole session as HAR.
- Safe by default: it turns itself off in TestFlight and App Store builds, redacts what you choose before anything is stored, and sends nothing off the device unless you ask.
Important
iOS and iPadOS 16+ · Swift 5.9 or later · No permissions · No Info.plist keys
One line of code to start. CI builds with Xcode 26.
![]() HTTP list |
![]() Log Inspector |
![]() Socket timeline |
![]() Files |
The Example app produced these, and it's a quick way to try Cerebro: open Example/CerebroExample.xcodeproj and run it on a simulator.
Pick one of these three options. They all need the same code.
In Xcode:
- Choose File > Add Package Dependencies.
- Enter
https://github.com/0xSiddhant/Cerebro.git. - Set Dependency Rule to Exact Version, using the latest release number.
- Add the Cerebro product to your app target. Add CerebroProto as well only if you decode protobuf.
In a Package.swift, with X.Y.Z as the latest release:
.package(url: "https://github.com/0xSiddhant/Cerebro.git", exact: "X.Y.Z"),.target(name: "MyApp", dependencies: [.product(name: "Cerebro", package: "Cerebro")]),SPM also downloads swift-protobuf, because the package declares it. Only CerebroProto links it.
platform :ios, '16.0'
target 'MyApp' do
pod 'Cerebro', :git => 'https://github.com/0xSiddhant/Cerebro.git', :tag => 'vX.Y.Z'
endReplace X.Y.Z with the latest release, then run pod install and open the .xcworkspace. Pod tags start with v, and SPM versions don't.
pod 'Cerebro', '~> 1.0' also works, from CocoaPods trunk. Trunk stops taking new versions on December 2, 2026, so it keeps the last release published before then. Anything newer comes only from Git, so prefer the line above.
- Download
Cerebro.xcframework.zipfrom the latest release and unzip it. - Drag
Cerebro.xcframeworkinto your project and tick your app target. - In the target's General > Frameworks, Libraries, and Embedded Content, set it to Embed & Sign. It's a dynamic framework, so without this the app crashes at launch with
Library not loaded: @rpath/Cerebro.framework/Cerebro.
Capture only needs that one zip. To decode protobuf, also add CerebroProto.xcframework.zip and SwiftProtobuf.xcframework.zip the same way. The release zips are built with Xcode 26, the only version CI tests, so use that or later.
Add one line as early as you can. Capture is added to a session's configuration when that configuration is created, so a session or configuration made before Cerebro.start() isn't captured. URLSession.shared is the one exception, because Cerebro reaches it another way.
UIKit:
import Cerebro
import UIKit
@main
final class AppDelegate: UIResponder, UIApplicationDelegate {
func application(
_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
) -> Bool {
Cerebro.start()
return true
}
}SwiftUI:
import Cerebro
import SwiftUI
@main
struct MyApp: App {
init() {
Cerebro.start()
}
var body: some Scene {
WindowGroup {
ContentView()
}
}
}Stored properties run first. If your AppDelegate or App has something like let api = APIClient(), that client exists before either method above runs, so create it after Cerebro.start() instead.
That one line is all most apps need. HTTP traffic and URLSessionWebSocketTask are captured from here on.
| Way | What it does |
|---|---|
| Floating button | Tap it to open the dashboard. Drag it to move it. Its number counts the requests since you last opened the dashboard |
| Shake | Hides or shows the floating button. It doesn't open the dashboard. In the simulator, use Device > Shake |
Cerebro.present() |
Opens the dashboard from your own debug menu or gesture. It does nothing while Cerebro is off |
| Close button | Top left of the dashboard. It returns you to your app |
Cerebro.stop() ends capture and removes the dashboard. A later Cerebro.start() begins a new session, and the one before it can still be read as a previous session.
The guide covers everything past setup:
| Topic | What's there |
|---|---|
| Features | What Cerebro captures and what the dashboard shows |
| Configuration | Every setting and its default |
| Redaction | Hiding tokens, cookies and body fields. Nothing is redacted until you select it |
| Traffic that needs code | NWConnection, Starscream and Socket.IO |
| Protobuf decoding | Showing binary protobuf as JSON, with rules in code or in a traffic_map.json file |
| System Info | Network status, addresses, performance, session totals, app and device info, and the opt-in public IP |
| Previous sessions | Reading the last session after a relaunch or a crash, and what's kept on disk |
| Export | Sharing a request as cURL or JSON, or the whole session as HAR |
| Files | Browsing, previewing, changing and sharing your app's files, and showing App Group containers |
| When Cerebro runs | On in simulators and development-signed builds, off elsewhere unless you opt in |
| What changes while Cerebro captures | Side effects on your app's requests |
| What Cerebro can't capture | WKWebView, AVPlayer and other limits |
| Troubleshooting | Common problems and fixes |
Bug reports and pull requests are welcome. CONTRIBUTING.md covers setup, the checks every change passes and the rules it follows. Each release's changes are in CHANGELOG.md.
MIT. See LICENSE.




