Install Buoy for Swift — Swift Package Manager setup for iOS

Requirements

An iOS app targeting iOS 16 or later, built with Xcode 16 or later.
A Free or Pro Buoy account key. Get one through your Buoy account.
A development build for the first setup and verification.

Buoy ships as a prebuilt, signed framework for iOS devices and the iOS Simulator. Mac Catalyst and macOS are not supported. Apps can use Swift 5 or Swift 6 language mode.

Install with your agent

Paste the prompt into Claude Code, Cursor or Codex. Your agent reads your app and picks the tools. Review its changes before you commit them.

Let your coding agent install itClaude Code · Cursor · Codex

Read the prompt before you paste it

Install Buoy, the in-app devtools, in this native iOS (Swift) project. Read the full instructions first: curl -fsSL https://buoy.gg/install-swift.md Read the raw text, not a summary. If curl is unavailable, use any HTTP tool you have. Ask me to paste the document only if nothing can fetch it. Do the install yourself: inspect the repo, run the commands, edit the files. Do not hand me steps you can run. Work out the routine decisions from the repo: which app target, SwiftUI or UIKit, how the project adds packages, where Buoy starts, where the overlay mounts. If Buoy is already partly installed, repair and extend it; never start Buoy twice or add a second overlay. When instructions conflict, follow this order: what I say here, then the document's rules about which packages exist and what needs my permission, then this project's own constraints, then the rest of the document, then your judgment. Ask me before: editing project.pbxproj by hand, opening a browser or creating an account, changing what a release build does beyond what the document specifies, or anything hard to undo. Do not commit. You are not done when the package installs. Build for the iOS Simulator if the project builds from the command line; add no tooling. Then report what you installed and why, what you skipped and why, every file you changed, what you verified, and the exact steps I take in Xcode and on the device to confirm the overlay appears and captures a request.

The prompt asks your agent to inspect the project, choose matching tools and guide setup. Review its edits and verify the connection on your device.Read the setup instructions

Add the package

In Xcode, choose File > Add Package Dependencies… and enter:

text

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

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

Use the dependency rule Up to Next Minor Version from 0.1.0. While the package is in 0.x, a minor version can contain breaking changes. Add the Buoy library product to your iOS app target.

In a Package.swift manifest:

swift

.package(url: "https://github.com/Buoy-gg/Buoy-Swift.git", .upToNextMinor(from: "0.1.0"))

.package(url: "https://github.com/Buoy-gg/Buoy-Swift.git", .upToNextMinor(from: "0.1.0"))

Import it with import Buoy. Every tool is part of that one module.

Account key

The examples read the key from a BUOY_LICENSE_KEY environment variable in your Xcode Run scheme. Xcode sets it only when it launches the app from that scheme. For other internal builds, supply the key through your app's own configuration.

swift

var config = BuoyConfig()
config.licenseKey = ProcessInfo.processInfo.environment["BUOY_LICENSE_KEY"]

var config = BuoyConfig()
config.licenseKey = ProcessInfo.processInfo.environment["BUOY_LICENSE_KEY"]

SwiftUI

Call Buoy.start(config) early, on the main actor, and add .buoyDevTools() to your root view. The Quick Start has a complete app.

Start Buoy before you create networking singletons or state objects that create URLSessions. Calling it in App.init can still be too late for clients created by stored-property initializers.

UIKit

Call Buoy.start(config) on the main actor early in your app lifecycle, with the same account configuration and compilation guard as the SwiftUI example. After creating your app window, install the overlay in its UIWindowScene:

swift

#if DEBUG
Buoy.install(in: windowScene)
#endif

#if DEBUG
Buoy.install(in: windowScene)
#endif

This belongs in your existing scene delegate, where windowScene is the scene attached to your app window. The SwiftUI modifier and the UIKit installer mount the same overlay.

Buoy Desktop

Open Buoy Desktop and sign in. The default broker URL is http://localhost:42831, which works for the iOS Simulator on the same Mac. For an iPhone or iPad, see Physical Devices.

Select the Swift device in Desktop and repeat the request check. A device connection and a populated Network panel are separate checks. Keep the default per-install device ID unless you need to manage identity yourself; a custom ID must be unique for each device.

Lifecycle

Calling Buoy.start again returns the existing runtime and can update a supplied account key. It does not change the broker URL or device identity of a running session, so set the initial configuration before starting.

Buoy.runtime?.stop() stops the runtime connection and account lifecycle. BuoyDevTools.uninstall() removes the overlay. Neither call removes networking hooks that were already installed.

Installation