Free trial
Documentation
Getting Started
Fundamentals
Desktop App
AI Automation
Available Tools
docs

Quick Start

This guide adds Buoy to a SwiftUI app and checks that a network request shows up. For UIKit, see Installation.

Let your agent do it

Your coding agent can set up Buoy for you. Use Claude Code, Cursor or Codex. Copy the prompt and paste it into your agent. Then review its changes.

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 steps below.

1. 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 and add the Buoy library to your app target.

2. Add your account key

In your app's Xcode Run scheme, add a BUOY_LICENSE_KEY environment variable containing your account key. Xcode passes it to the app only when it launches the app from that scheme.

3. Start Buoy

Start Buoy in the app's initializer and add the overlay to your root view. Both are behind #if DEBUG, so Release builds never run Buoy:

swift
import Foundation
import SwiftUI
import Buoy

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

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

@MainActor
struct RequestCheckView: View {
    @State private var result = "Ready"

    var body: some View {
        VStack(spacing: 16) {
            Text(result)
            Button("Send test request") {
                Task { await sendRequest() }
            }
        }
        .padding()
    }

    private func sendRequest() async {
        guard let url = URL(string: "https://example.com/") else { return }
        let configuration = URLSessionConfiguration.ephemeral
        configuration.requestCachePolicy = .reloadIgnoringLocalCacheData
        let session = URLSession(configuration: configuration)
        defer { session.finishTasksAndInvalidate() }
        do {
            let (_, response) = try await session.data(from: url)
            if let response = response as? HTTPURLResponse {
                result = "HTTP \(response.statusCode)"
            }
        } catch {
            result = error.localizedDescription
        }
    }
}

import Foundation
import SwiftUI
import Buoy

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

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

@MainActor
struct RequestCheckView: View {
    @State private var result = "Ready"

    var body: some View {
        VStack(spacing: 16) {
            Text(result)
            Button("Send test request") {
                Task { await sendRequest() }
            }
        }
        .padding()
    }

    private func sendRequest() async {
        guard let url = URL(string: "https://example.com/") else { return }
        let configuration = URLSessionConfiguration.ephemeral
        configuration.requestCachePolicy = .reloadIgnoringLocalCacheData
        let session = URLSession(configuration: configuration)
        defer { session.finishTasksAndInvalidate() }
        do {
            let (_, response) = try await session.data(from: url)
            if let response = response as? HTTPURLResponse {
                result = "HTTP \(response.statusCode)"
            }
        } catch {
            result = error.localizedDescription
        }
    }
}

In an existing app, keep your root view and add .buoyDevTools() to it. Start Buoy before you create networking singletons or state objects that create URLSessions; sessions created before Buoy.start are not captured.

4. Check the first request

Run the app in the iOS Simulator. Open the Buoy launcher and complete any account prompt. Then tap Send test request, open Network, and select the example.com request to see its URL, status and response.

If the request is missing, check that the button made a fresh request, the session was created after Buoy.start, and capture is on. Requests made before interception or account access started are not recorded.

5. Open it in Buoy Desktop

Open Buoy Desktop on the same Mac and sign in. The simulator app connects to it automatically. For an iPhone or iPad, follow Physical Devices.

Edit on GitHub
Overview
Installation