Cerebro

1.0.1

See every request your iOS app makes, and every file it keeps, from inside the app. A debug-only inspector for HTTP, WebSockets, live SSE and protobuf: one line to start, no permissions, and nothing leaves the device unless you ask.
0xSiddhant/Cerebro

What's New

v1.0.1

2026-11-14T10:30:08Z

Install

Pick one of these three options.

Swift Package Manager

.package(url: "https://github.com/0xSiddhant/Cerebro.git", exact: "1.0.1")

CocoaPods

pod 'Cerebro', :git => 'https://github.com/0xSiddhant/Cerebro.git', :tag => 'v1.0.1'

XCFramework

Download the .xcframework.zip files below, unzip them, and add them to your app target with Embed & Sign.

To generate rules from traffic_map.json in a Run Script phase, also download cerebro-proto-gen.zip.

What's Changed

  • fix: keep cerebro-proto-gen in CocoaPods installs by @0xSiddhant in #18

Full Changelog: v1.0.0...v1.0.1

Cerebro's icon: a glowing violet globe on a near-black background, with the signals it has found on its surface

Cerebro

See every request your iOS app makes, and every file it keeps, from inside the app.

CI Release Latest release License: MIT iOS 16+ Swift 5.9+ SPM compatible CocoaPods via Git

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, including URLSession.shared and 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.

Requirements

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.

Screenshots

A tour of Cerebro in the Example app. The floating button opens the dashboard, a search narrows the HTTP list, and a request's Request and Metrics pages open. The app then turns dark and shows a socket's timeline, the Proto Config rules, the Files tab down to a property list shown as a tree, and the three System Info pages, before closing back to the app.

The HTTP list in light mode, with a search field, status filters, and one card per request with a coloured method tag and a status badge
HTTP list
The Log Inspector in dark mode on a request's Response page, with its time, size, type and protocol, a body preview, and the response headers
Log Inspector
A socket's timeline in light mode, with the frame sent in violet on the right and the reply on the left
Socket timeline
The Files tab in dark mode on a folder of sample files, each with its icon, size and date
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.

Getting started

1. Install

Pick one of these three options. They all need the same code.

Swift Package Manager

In Xcode:

  1. Choose File > Add Package Dependencies.
  2. Enter https://github.com/0xSiddhant/Cerebro.git.
  3. Set Dependency Rule to Exact Version, using the latest release number.
  4. 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.

CocoaPods

platform :ios, '16.0'

target 'MyApp' do
  pod 'Cerebro', :git => 'https://github.com/0xSiddhant/Cerebro.git', :tag => 'vX.Y.Z'
end

Replace 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.

XCFramework

  1. Download Cerebro.xcframework.zip from the latest release and unzip it.
  2. Drag Cerebro.xcframework into your project and tick your app target.
  3. 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.

2. Start Cerebro

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.

3. Open the dashboard

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.

Learn more

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

Contributing

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.

License

MIT. See LICENSE.

Description

  • Swift Tools 5.9.0
View More Packages from this Author

Dependencies

Last updated: Sun Nov 22 2026 01:35:52 GMT-1000 (Hawaii-Aleutian Standard Time)