---
name: buoy-install-flutter
description: Install Buoy in a Flutter app, configure account access, and verify the result.
---

# Install Buoy in a Flutter app

Use this guide for Flutter apps. The full manual setup, including the list of individual packages, is https://buoy.gg/buoy/latest/docs/flutter/installation.md (raw markdown). Read it when this page leaves a question open.

Check that this guide fits the repo. If it does not, use the right guide. React Native or Expo: https://buoy.gg/install.md. React Native TV: https://buoy.gg/install-tv.md. Flutter: https://buoy.gg/install-flutter.md. Native iOS: https://buoy.gg/install-swift.md. Native Android: https://buoy.gg/install-android.md. .NET MAUI: https://buoy.gg/install-maui.md. React web: https://buoy.gg/install-web.md. Angular: https://buoy.gg/install-angular.md. Solid: https://buoy.gg/install-solid.md. Vue or Nuxt: https://buoy.gg/install-vue.md. React with Capacitor or Ionic: https://buoy.gg/install-capacitor.md.

## Rules that do not bend

The user's explicit instructions outrank this section. The target project's own conventions do not.

- Install only packages the Flutter guide names: the `buoy` umbrella, `buoy_core`, and the `buoy_*` tool packages it lists. Do not guess package names.
- Never add a dependency beyond the Buoy packages to make a tool work. Skip the tool and say so in the report.
- Ask the user before: adding any non-Buoy dependency, running anything that opens a browser, or when more than one app in the repo could be the target. Decide everything else from the repository and report the decision.
- Keep the diff to the install. The user reviews it as a pull request. No reformatting, no added comments, no refactors, no new lint or formatter configuration, no test buttons or sample requests added to the app.
- Do not read or print `.env*` files, keys, or credentials, in the project or the home directory. Never write an account key into source code.
- Do not stash, checkout, reset, add worktrees, or discard the user's work. Compare against the starting state with `git diff`.
- Do not commit. Leave the changes in the working tree.

## 0. Scope

Check the app's `pubspec.yaml` for `buoy` or `buoy_core` before changing anything.

- Absent: a fresh install. Do every step below.
- Present: keep the existing `BuoyDevTools` mount and its options. Add the missing tools or repair the setup, then verify.

Never wrap the app in a second `BuoyDevTools`.

## 1. Identify the app

- The app is the `pubspec.yaml` that depends on the Flutter SDK and has `lib/main.dart`. In a monorepo, pick that package and run every command from its directory. If several qualify, ask which one.
- The package manifests require Dart `^3.9.0` and Flutter `>=3.27.0`. Check with `flutter --version`. If the SDK is older, stop and tell the user.
- Find the `MaterialApp` or `CupertinoApp`. The menu mounts through its `builder`.

## 2. Add the package

Use the umbrella unless the user asked for a smaller set:

```bash
flutter pub add buoy
```

The umbrella registers its bundled tools. With individual packages, every tool needs its registration call before `runApp` (for example `registerBuoyNetwork()` from `buoy_network`). Adding a dependency alone does not register a tool.

React Query, Redux, Zustand, render highlighting, debug borders, and JS Top are React Native tools. Do not look for Flutter versions of them.

## 3. Mount the menu

Wrap the app through `builder`, inside any providers the tools need:

```dart
import 'package:buoy/buoy.dart';

MaterialApp(
  builder: (context, child) => BuoyDevTools(
    licenseKey: const String.fromEnvironment('BUOY_KEY'),
    child: child ?? const SizedBox.shrink(),
  ),
  // the app's existing arguments stay as they are
)
```

If the app already has a `builder`, keep it and pass its result as the `child` of `BuoyDevTools`. `BuoyDevTools` runs in debug mode. In profile and release builds it returns only the app's child, so no extra guard is needed.

Some tools need app-specific setup, such as connecting a router or supplying environment values. Their pages are under https://buoy.gg/buoy/latest/docs/flutter/tools/. Wire only the tools whose setup the app supports, and list the rest in the report.

## 4. Account

A Free or Pro Buoy account is required. The user signs in. A key is only a backup. Sign-in opens a browser. So give the user this command to run in the app folder:

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

It writes a dev token as `BUOY_KEY` to `.env.local`. The token opens debug builds for 30 days. The widget reads it with `String.fromEnvironment('BUOY_KEY')`. So the user runs the app with that file:

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

They add the same flag to their IDE run setup. Do not write the token or a key into source or a launch configuration. Mark account setup as pending in the report.

The app can also let the user sign in with a code. Pass `signIn: const BuoySignIn(appId: '<bundle id>')` to `BuoyDevTools`. See https://buoy.gg/buoy/latest/docs/sign-in.md (Flutter section). A key from https://buoy.gg/dashboard/licenses is the backup: `flutter run --dart-define=BUOY_KEY=<key>`.

## 5. Verify

Static, which you do: confirm `flutter pub get` succeeded and run `flutter analyze` with the project's existing analysis options. Do not add lint rules.

Device, which the user does: run the app in debug with the dev token, tap the floating button, confirm the menu opens and includes Network, then do something in the app that makes a new HTTP request and inspect it in Network.

Desktop and MCP are optional. Set them up only when asked: https://buoy.gg/buoy/latest/docs/desktop.md and https://buoy.gg/buoy/latest/docs/mcp.md. The iOS Simulator reaches the computer at `localhost`, the Android Emulator at `10.0.2.2`, and a physical device needs `socketUrl` set to the computer's LAN address.

## 6. Report the result

List the target app, installed versions, skipped tools and reasons, changed files, account-setup status, checks performed, and any exact blocking errors. Give the user the remaining steps. Do not print keys or claim that compiling proves capture.