Installation

Install Buoy in an existing Flutter app and open its floating tool menu. The BuoyDevTools widget runs in debug mode; in profile and release builds it returns only your app's child widget.

Requirements

The package manifests require Dart ^3.9.0 and Flutter >=3.27.0. Use a Flutter SDK that includes Dart 3.9 or a compatible newer Dart 3 release. Check your installed versions with:

flutter --version

flutter --version

Quick Start

For the full suite, run this from your Flutter app's directory:

flutter pub add buoy

flutter pub add buoy

Wrap your app through MaterialApp.builder. A complete minimal lib/main.dart looks like this:

import 'package:flutter/material.dart';
import 'package:buoy/buoy.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      builder: (context, child) => BuoyDevTools(
        licenseKey: const String.fromEnvironment('BUOY_KEY'),
        child: child ?? const SizedBox.shrink(),
      ),
      home: const Scaffold(
        body: Center(child: Text('Open the Buoy menu to inspect this app.')),
      ),
    );
  }
}

import 'package:flutter/material.dart';
import 'package:buoy/buoy.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      builder: (context, child) => BuoyDevTools(
        licenseKey: const String.fromEnvironment('BUOY_KEY'),
        child: child ?? const SizedBox.shrink(),
      ),
      home: const Scaffold(
        body: Center(child: Text('Open the Buoy menu to inspect this app.')),
      ),
    );
  }
}

Get your account key as described below, then start a debug build:

flutter run --dart-define=BUOY_KEY=YOUR_LICENSE_KEY

flutter run --dart-define=BUOY_KEY=YOUR_LICENSE_KEY

Tap the floating button. Confirm that the menu opens and includes Network. To check capture, perform an action in your app that makes a new HTTP request, then open Network and inspect it. The minimal app above opens the menu but does not make a request.

Available Packages

The buoy umbrella registers its bundled tools. Some tools still need app-specific setup, such as connecting a router or supplying environment values. Their pages describe those steps.

Camera

Supply camera feeds to supported iOS Simulator apps. Desktop account required; screen capture and non-QR generation need Pro.

Nothing to install — ships with Buoy Desktop

Core

Required

Account, menu and connection setup for Flutter tools in debug builds.

flutter pub add buoy_core

Network

Inspect supported dart:io HttpClient traffic captured after setup.

flutter pub add buoy_network

Storage

Inspect configured storage adapters and supported write events or editing controls.

flutter pub add buoy_storage

Environment

Validate explicitly supplied environment values against configured expectations.

flutter pub add buoy_env

Console

Inspect supported logs captured after setup in a debug build.

flutter pub add buoy_console

Routes

Inspect configured go_router navigation and supported route actions.

flutter pub add buoy_routes

Images

Inspect image loads tracked by BuoyImage and available size or cache signals.

flutter pub add buoy_images

Events Timeline

Review captured events from configured sources in a shared timeline.

flutter pub add buoy_events

Riverpod

Inspect provider observations captured through the configured Riverpod observer.

flutter pub add buoy_riverpod

Perf Monitor

View frame and resource metrics available for the Flutter platform and runtime.

flutter pub add buoy_perf_monitor

Impersonate

Test identities through an explicitly configured, backend-authorized flow.

flutter pub add buoy_impersonate

Image Overlay

Pin a design mockup over the running app for pixel-perfect UI.

flutter pub add buoy_image_overlay

Prefer one install? flutter pub add buoy pulls in the whole suite (umbrella package).

To install only Network and the core widget:

flutter pub add buoy_core buoy_network

flutter pub add buoy_core buoy_network

Use these imports in place of the umbrella import:

import 'package:buoy_core/buoy_core.dart';
import 'package:buoy_network/buoy_network.dart' show registerBuoyNetwork;

import 'package:buoy_core/buoy_core.dart';
import 'package:buoy_network/buoy_network.dart' show registerBuoyNetwork;

Register Network before runApp; keep the MyApp widget from the example above:

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  registerBuoyNetwork();
  runApp(const MyApp());
}

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  registerBuoyNetwork();
  runApp(const MyApp());
}

Individual tool packages need their registration calls. Adding a dependency alone does not register it with the core widget.

Register Your License Key

Use a Free or Pro Buoy account key. Visit pricing for account options and plan limits. Pass the key through --dart-define=BUOY_KEY=... as shown above; the widget reads it with String.fromEnvironment.

If the widget shows account setup, confirm that the build received the key and complete the prompt. A Pro key does not enable this widget in profile or release mode.

Desktop & AI (optional)

• Buoy Desktop provides a free desktop dashboard for connected apps.
• AI / MCP Server lets Claude Code, Cursor, or another MCP editor inspect and control your app. MCP requires Pro.

For MCP configuration, run:

npx -y @buoy-gg/mcp@latest init

npx -y @buoy-gg/mcp@latest init

Keep the Flutter app running in debug mode with BuoyDevTools mounted. Follow the connection guide for your chosen surface.

Devices

• iOS Simulator uses localhost; Android Emulator uses 10.0.2.2 to reach the computer running Desktop or the MCP broker.
• On a physical device, set socketUrl to your computer's LAN address, for example BuoyDevTools(socketUrl: 'http://192.168.1.20:42831', child: child). Replace the address with your computer's address and keep the device on a network that can reach it. Allow local network access if iOS asks.

If the device does not appear, confirm that the broker is running, the address is correct, and the network or firewall allows the connection.

Dart Support

Buoy's Flutter implementation is Dart. Its dependencies may include Flutter plugins, so follow any platform setup required by the packages you install.

Monorepos & Enterprise Setups

After adding packages or changing tool registration, stop and restart the app. For individual packages, call each tool's registration function before using it.

Flutter and React Native devices can connect to the same Desktop or MCP broker. Physical Flutter devices need an explicit reachable socketUrl.

Keep BuoyDevTools mounted for the setup on this page. Removing it also removes the initialization and connection it manages; this guide does not provide a separate headless setup.

Not on Flutter (yet)

React Query, Redux, Zustand, render highlighting, debug borders, and JS Top are React Native tools. Check each Flutter tool page for supported features; a matching tool name does not imply complete feature parity. See the roadmap for proposed additions.

Next Steps

• Quick Start: Flutter setup and usage
• BuoyDevTools: widget reference
• Buoy Desktop: desktop connection setup
• AI / MCP Server: connect your AI editor
• Custom Tools: add an app-specific tool

FAQ

What's the difference between the buoy umbrella and the individual packages?

buoy imports and registers its bundled tools. Individual packages let you choose a smaller set, with explicit registration for each tool. Both use a BuoyDevTools widget, but the umbrella exports its own wrapper around the core widget.

Where do I mount BuoyDevTools in a Flutter app?

Use MaterialApp.builder or CupertinoApp.builder to wrap the child so the menu appears above your screens. Keep it inside any providers needed by your tools.