Documentation
docs

Overview

Buoy on your iPhone, in 2 minutes

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 it
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

To install by hand, follow the Quick Start.

What you get

One import Buoy brings in every tool:

ToolWhat it covers on iOS
NetworkURLSession requests on default and ephemeral configurations, response overrides and throttling
ConsoleThe app's native console output
StorageUserDefaults, registered keychain items and registered MMKV instances
EnvValues and validation rules you supply
ImpersonateUser search and impersonation headers on captured requests
Image OverlayA design image laid over the running app
ImagesLoading, failure, retry, blank and replacement states for BuoyAsyncImage
NotificationsReceived notifications, responses, permissions and local test delivery
RoutesScreens, route patterns and navigation
ScenariosReviewed, repeatable app setups, with recording in development builds
Time MachineSnapshots and live restore of UserDefaults and MMKV
EventsOne timeline of network, storage and route activity
AssetsBundle resource sizes, duplicates and baselines

Tools that depend on JavaScript stores or React rendering, such as React Query, Redux or Highlight Updates, are not part of the Swift SDK.

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 key.
  • 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