---
name: buoy-install-swift
description: Install Buoy in a native iOS (Swift) app, configure account access, and verify the result.
---

# Install Buoy in a native iOS app

Use this guide for native iOS apps written in Swift (SwiftUI or UIKit). The full manual setup is https://buoy.gg/buoy/latest/docs/swift/installation.md and https://buoy.gg/buoy/latest/docs/swift/quick-start.md (raw markdown). Read them when this page leaves a question open.

Check that this guide fits the repo. If it does not, use the right guide. React Native or Expo: https://buoy.gg/install.md. React Native TV: https://buoy.gg/install-tv.md. Flutter: https://buoy.gg/install-flutter.md. Native iOS: https://buoy.gg/install-swift.md. Native Android: https://buoy.gg/install-android.md. .NET MAUI: https://buoy.gg/install-maui.md. React web: https://buoy.gg/install-web.md. Angular: https://buoy.gg/install-angular.md. Solid: https://buoy.gg/install-solid.md. Vue or Nuxt: https://buoy.gg/install-vue.md. React with Capacitor or Ionic: https://buoy.gg/install-capacitor.md.

## Rules that do not bend

The user's explicit instructions outrank this section. The target project's own conventions do not.

- Buoy for Swift is one package, `https://github.com/Buoy-gg/Buoy-Swift.git`, with one library product, `Buoy`. Every tool is part of that one module. Add nothing else.
- Do not hand-edit `project.pbxproj` without asking. It is hard to review and easy to break.
- Ask the user before: editing `project.pbxproj`, running anything that opens a browser, or when more than one app target could be the target. Decide everything else from the repository and report the decision.
- Keep the diff to the install. The user reviews it as a pull request. No reformatting, no added comments, no refactors, no new lint or formatter configuration, no test buttons or sample requests added to the app.
- Do not read or print `.env*` files, keys, or credentials, in the project or the home directory. Never write an account key into source code.
- Do not stash, checkout, reset, add worktrees, or discard the user's work. Compare against the starting state with `git diff`.
- Do not commit. Leave the changes in the working tree.

## 0. Scope

Search the project for `Buoy-Swift` and `import Buoy` before changing anything. If Buoy is already set up, keep the existing `Buoy.start` call and overlay, then repair or verify. Never start Buoy twice or add a second overlay.

## 1. Identify the app

- The target is an iOS app target. Buoy needs iOS 16 or later and Xcode 16 or later. Mac Catalyst and macOS are not supported. If the deployment target is older than iOS 16, stop and tell the user.
- SwiftUI apps have an `@main` type that conforms to `App`. UIKit apps have a scene delegate.
- How the project is defined decides how the package is added: `Package.swift`, a project generator such as XcodeGen (`project.yml`) or Tuist, or a plain `.xcodeproj`.

## 2. Add the package

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.

- `Package.swift` or a project generator: add it in that file, for example `.package(url: "https://github.com/Buoy-gg/Buoy-Swift.git", .upToNextMinor(from: "0.1.0"))`, and add the `Buoy` product to the app target.
- A plain `.xcodeproj`: give the user the Xcode steps (File > Add Package Dependencies…, enter the URL above, add the **Buoy** library to the app target) and do the code changes yourself. Edit `project.pbxproj` only if the user says to.

## 3. Start Buoy and mount the overlay

Start Buoy early, on the main actor, behind `#if DEBUG`. Start it before networking singletons or state objects that create URLSessions; `App.init` can still be too late for clients made by stored-property initializers.

SwiftUI:

```swift
import Buoy

#if DEBUG
var config = BuoyConfig()
config.licenseKey = ProcessInfo.processInfo.environment["BUOY_LICENSE_KEY"]
Buoy.start(config)
#endif
```

Then add `.buoyDevTools()` to the root view inside the `WindowGroup`, also behind `#if DEBUG`.

UIKit: call `Buoy.start(config)` the same way early in the app lifecycle, then install the overlay in the existing scene delegate after the window is created:

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

## 4. Account

A Free or Pro Buoy account key is required. The code above reads `BUOY_LICENSE_KEY` from the Xcode Run scheme's environment, which Xcode sets only when it launches the app from that scheme. Do not write the key into source or into a shared scheme file. Tell the user to add the variable to their Run scheme and where to get a key: https://buoy.gg/pricing. If the user prefers signing in to a key, see https://buoy.gg/buoy/latest/docs/sign-in.md (Swift section). Mark account setup as pending in the report.

## 5. Verify

Static, which you do: if the project builds from the command line, build it for the iOS Simulator with `xcodebuild`. If the package was not added yet because the user has to do it in Xcode, say that the build check is still pending.

Device, which the user does: run a debug build from Xcode, open the Buoy overlay, do something in the app that makes a new HTTP request, and inspect it in Network.

Desktop is optional: https://buoy.gg/buoy/latest/docs/desktop.md. The iOS Simulator reaches Desktop at `http://localhost:42831` with no setup. Physical devices: https://buoy.gg/buoy/latest/docs/swift/devices.md.

## 6. Report the result

List the target app, installed versions, skipped tools and reasons, changed files, account-setup status, checks performed, and any exact blocking errors. Give the user the remaining steps. Do not print keys or claim that compiling proves capture.