Quick Start

Open Buoy in a Flutter debug build, then inspect a request. You need a Free or Pro Buoy account. Profile and release builds do not show the widget or start its tools, unless you opt in.

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.

To install by hand, follow the steps below.

1. Install the core

flutter pub add buoy

flutter pub add buoy

The buoy umbrella pulls in the whole suite. Prefer à la carte? See Installation.

2. Add to your app

Wrap your app via MaterialApp.builder (or CupertinoApp.builder):

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

MaterialApp(
  builder: (context, child) => BuoyDevTools(
    child: child ?? const SizedBox.shrink(),
  ),
)

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

MaterialApp(
  builder: (context, child) => BuoyDevTools(
    child: child ?? const SizedBox.shrink(),
  ),
)

A floating button appears in the corner of your app. Tap it to open the menu.

Sign in from your app folder. Your browser opens, and you click Allow. This writes a dev token to .env.local:

npx --package=@buoy-gg/core buoy login

npx --package=@buoy-gg/core buoy login

Then run the app with that file. BuoyDevTools reads the token by itself:

flutter run --dart-define-from-file=.env.local

flutter run --dart-define-from-file=.env.local

The token works for 30 days. Then run buoy login again.

See Installation for a complete app example and SDK requirements.

3. Add tools

The umbrella registers its bundled Flutter tools. Perform an action that makes an HTTP request, then open Network and select the new row. Check the URL and response. If no row appears, confirm that the action made a fresh request and uses a supported client.

Individual packages require explicit registration. Follow the standalone Network example in Installation.

Riverpod providers

If you use Riverpod, add the Buoy observer to your ProviderScope:

import 'package:flutter/widgets.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:buoy_riverpod/buoy_riverpod.dart';

void main() {
  registerBuoyRiverpod();
  runApp(
    ProviderScope(
      observers: const [buoyRiverpodObserver],
      child: const MyApp(),
    ),
  );
}

import 'package:flutter/widgets.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:buoy_riverpod/buoy_riverpod.dart';

void main() {
  registerBuoyRiverpod();
  runApp(
    ProviderScope(
      observers: const [buoyRiverpodObserver],
      child: const MyApp(),
    ),
  );
}

The observer reports provider changes to the Riverpod tool. See Riverpod for package requirements and complete integration.

go_router

If you use go_router, pass your router once at registration:

import 'package:buoy_routes/buoy_routes.dart';

registerBuoyRoutes(router: myGoRouter);

import 'package:buoy_routes/buoy_routes.dart';

registerBuoyRoutes(router: myGoRouter);

Available tools

Package	What you get
Buoy Desktop	Supply camera feeds to supported iOS Simulator apps. Desktop account required; screen capture and non-QR generation need Pro.
buoy_network	Inspect supported dart:io HttpClient traffic captured after setup.
buoy_storage	Inspect configured storage adapters and supported write events or editing controls.
buoy_env	Validate explicitly supplied environment values against configured expectations.
buoy_console	Inspect supported logs captured after setup in a debug build.
buoy_routes	Inspect configured go_router navigation and supported route actions.
buoy_images	Inspect image loads tracked by BuoyImage and available size or cache signals.
buoy_events	Review captured events from configured sources in a shared timeline.
buoy_riverpod	Inspect provider observations captured through the configured Riverpod observer.
buoy_perf_monitor	View frame and resource metrics available for the Flutter platform and runtime.
buoy_impersonate	Test identities through an explicitly configured, backend-authorized flow.
buoy_image_overlay	Pin a design mockup over the running app for pixel-perfect UI.

Use the umbrella for the bundled suite, or register a smaller set of individual packages.

Control who sees devtools

Mount BuoyDevTools only when your app allows the current tester to inspect its data. Use your existing authorization checks. Omitting the widget also omits the initialization and connection it manages; it is not a desktop-only mode.

Take it further

You can also connect this debug build to Desktop or MCP:

• Buoy Desktop — mirror every tool to a full dashboard on macOS, Windows, or Linux, with a live performance HUD and multi-device switching.
• AI / MCP Server — let Claude Code, Cursor, or any MCP editor inspect and control your running app. One command to wire it up:

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

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

Buoy Desktop is free to use; the MCP server is free in its basic form. Pro adds the full MCP. Both connect to the same app you just set up — Flutter devices appear next to React Native ones.

What's next

• BuoyDevTools — Core widget reference
• Buoy Desktop — The full desktop dashboard
• AI / MCP Server — Drive your app from your AI editor
• Custom Tools — Build your own debugging tools

FAQ

How do I add Buoy devtools to a Flutter app?

Run flutter pub add buoy, then wrap your app in BuoyDevTools via MaterialApp.builder. A floating button appears in the corner — tap it to open the menu. With the umbrella install, every Flutter tool is already registered.

Do I need a license key to try it?

No. Sign in with a Free or Pro account, using buoy login. A key still works if you have one. Pro adds paid features, like the full MCP. It does not turn on the Flutter widget in profile or release mode.