Buoy for Swift: in-app debugging tools for native iOS

Buoy for Swift is a Swift package that ships as a prebuilt, signed framework. It needs iOS 16 or later and Xcode 16 or later, and works in apps that use Swift 5 or Swift 6 language mode. In Xcode, choose File > Add Package Dependencies…, enter the URL below and use the rule Up to Next Minor Version from 0.1.0.

https://github.com/Buoy-gg/Buoy-Swift.git

Then start Buoy and add the overlay, both behind #if DEBUG:

import SwiftUI
import Buoy

@main
struct MyApp: App {
    init() {
        #if DEBUG
        var config = BuoyConfig()
        config.licenseKey = ProcessInfo.processInfo.environment["BUOY_LICENSE_KEY"]
        Buoy.start(config)
        #endif
    }

    var body: some Scene {
        WindowGroup {
            #if DEBUG
            ContentView().buoyDevTools()
            #else
            ContentView()
            #endif
        }
    }
}

Run npx --package=@buoy-gg/core buoy login in your project folder. Put the token it writes in a BUOY_LICENSE_KEY environment variable in the Xcode Run scheme. UIKit apps call Buoy.install(in: windowScene) from the scene delegate instead of the modifier. The Swift quick start walks through the first captured request.

The package bundles the tools below in one module, so a single import Buoy brings them all in. Network and Console start with Buoy.start; the others need a line of configuration or a view modifier to reach your app's state. Each card links to its setup. Each tool works like its React Native version, and the guide says where Swift is different.

A Swift app connects to Buoy Desktop the same way a React Native app does, and appears next to your other devices. In the iOS Simulator it finds Desktop on its own. On an iPhone, set BUOY_SOCKET_URL to your computer's address in the Run scheme and add the local network and App Transport Security entries from the physical devices guide. Buoy prints a [Buoy] setup: line in the Xcode console when one is missing.

With a Pro account, the Buoy MCP server lets an AI agent in your editor read captured requests and logs, tap supported UI elements, navigate between routes and restore Time Machine snapshots in the running app.

Your app decides whether Buoy runs. Swift packages cannot be linked only in Debug, so the framework is embedded in every build, but nothing runs until Buoy.start is called: no URLProtocol registration, no swizzling, no overlay window and no network connection. Keep both calls behind #if DEBUG and a Release build never executes it. Scenario runs and UI recording also check at runtime that the app is a development build.

The framework adds about 9 MB to an uncompressed arm64 Release build, measured before App Store thinning. The Release builds guide has the details.

Flipper was a desktop debugging platform for mobile apps, and its owner has archived the repository on GitHub. Buoy covers part of the same ground for native iOS: it inspects network traffic, logs and stored values from inside a debug build and shows them in a desktop app. It is a different tool with its own setup, so check the Tools guide for what each Swift tool captures before planning a move.

Buoy for Swift runs on iOS devices and the iOS Simulator; Mac Catalyst and macOS are not supported. Tools built on JavaScript stores, such as React Query, Redux, Zustand and Jotai, are React Native only. So are JS Top, Three and Sentry. Where a Swift tool works in a different way, the Tools guide lists each gap. Report problems on the issue tracker.