Documentation
Mobile
Web
TV
All but React Native are in beta.
Getting Started
Fundamentals
Desktop App
On this page
Buoy for Swift adds Buoy's developer tools to a native iOS app built with SwiftUI or UIKit. It is a separate SDK from the React Native packages: one Swift package, Buoy-Swift, that ships as a prebuilt, signed framework.
Swift support is in beta. The tools work on the device, in Buoy Desktop and through the MCP server, but they do not match the React Native tools feature for feature. Each tool section in Tools lists what the native version leaves out.
Start here
Let your coding agent install Buoy in your app:
Let your coding agent install itClaude Code · Cursor · Codex
Read the prompt before you paste itHide the prompt
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
To install by hand, follow the Quick Start.
What you get
One import Buoy brings in every tool:
| Tool | What it covers on iOS |
|---|---|
| Network | URLSession requests on default and ephemeral configurations, response overrides and throttling |
| Console | The app's native console output |
| Storage | UserDefaults, registered keychain items and registered MMKV instances |
| Env | Values and validation rules you supply |
| Impersonate | User search and impersonation headers on captured requests |
| Image Overlay | A design image laid over the running app |
| Images | Loading, failure, retry, blank and replacement states for BuoyAsyncImage |
| Notifications | Received notifications, responses, permissions and local test delivery |
| Routes | Screens, route patterns and navigation |
| Scenarios | Reviewed, repeatable app setups. Recording needs a development build |
| Time Machine | Snapshots and live restore of UserDefaults and MMKV |
| Events | One timeline of network, storage and route activity |
| Assets | Bundle resource sizes, duplicates and baselines |
| Clock | Jump, freeze or speed up time read through BuoyClock.now() and Buoy's timers |
| Lifecycle | What the app does when people leave and come back |
| Location | Fake places, routes and geofences for BuoyLocationProvider |
| Permissions | Denied, blocked, limited and not-asked states for BuoyPermissions checks |
| Bench | A floating speed HUD, plus benchmarks you can record and compare |
| Highlight | Redraws of views marked with .buoyTrackRenders |
| Debug Borders | Outlines around views, to check layout |
| Ask Buoy | Chat about the app in plain English and use its tools |
Tools for JavaScript stores, such as React Query, Redux, Zustand and Jotai, are not part of the Swift SDK. Neither are JS Top and Three. Sentry is not on Swift yet.
Requirements
- An iOS app targeting iOS 16 or later, built with Xcode 16 or later. Apps can use Swift 5 or Swift 6 language mode.
- A Free or Pro Buoy account.
- A development build for the first setup.
Buoy runs on iOS devices and the iOS Simulator. Mac Catalyst and macOS are not supported.
Next steps
- Quick Start: add the package and check your first captured request.
- Installation: package versions, sign-in and UIKit setup.
- Physical Devices: connect an iPhone or iPad to Buoy Desktop.
- Release Builds: keep Buoy out of the builds you ship.