---
name: buoy-install-maui
description: Add Buoy to a MAUI app and check it.
---

# Add Buoy to a .NET MAUI app

Read https://buoy.gg/buoy/latest/docs/maui/installation.md first.
Then read https://buoy.gg/buoy/latest/docs/maui/quick-start.md.
Use the raw Markdown from those links.

## Rules

Follow the user's scope and the repo's rules.
Keep edits small and leave other work in place.
Do not commit or discard files.
Do not read or print keys or env files.
Do not put keys in source code.
Ask before a new account or a browser sign-in.
Ask before you change the target or OS floor.
Do not add test screens or a second app host.

## Find the app

Find the app's csproj.
Find its MauiProgram setup too.
Check UseMaui and each target.
Search for Buoy.Maui and UseBuoy before you add them.
Keep an existing host; do not call UseBuoy twice.
If several apps fit, ask which one to use.

Use .NET 10 with its matching MAUI workload.
The host uses Microsoft.Maui.Controls 10.0.20.
The repo pins SDK and workload set 10.0.200.
These are the package targets and OS floors:

- net10.0-ios: iOS 15.0.
- net10.0-android: Android API 24.
- net10.0-maccatalyst: Mac Catalyst 15.0.

There is no Windows target in this package.
Mac Catalyst has a build target.
We do not claim it passed tests here.
If this is not a MAUI app, use its own guide.
Find the other guides at https://buoy.gg/llms.txt.

## Add the package

This command is for the first NuGet beta.
If it is not live yet, report that block.
Do not use some other package or source.
Run this in the app's project folder:

```sh
dotnet add package Buoy.Maui --prerelease
```

Buoy.Core comes with it. Keep the resolved version.
Guard that PackageReference so it is Debug-only:

```xml
Condition="'$(Configuration)' == 'Debug'"
```

Guard each direct Buoy package and BuoyPlugin item too.
If the csproj lists a Windows target, skip Windows too:

```xml
Condition="'$(Configuration)' == 'Debug' and $([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) != 'windows'"
```

Then guard Buoy code with #if DEBUG && !WINDOWS.
Remove any Buoy entry that has no guard.
Read https://buoy.gg/buoy/latest/docs/maui/release-builds.md.

## Wire the host and tools

Guard imports and Buoy code with #if DEBUG.
Keep real app paths for Release builds.
Add UseBuoyNetwork and one UseBuoy call before Build.
Use services.CreateNetworkClient for the app's HTTP client.
Keep its auth and headers.
Keep its transport setup too.
Do not add a client that the app never uses.
A plain new HttpClient call skips Buoy.
The host adds its view to the MAUI window.
Do not wrap or replace the app's pages.

Read https://buoy.gg/buoy/latest/docs/maui/tools.md for each tool.
Add only tools that fit the app's data sources.
List known store keys with their real types.
List route shapes and bind the app's Shell or NavigationPage.
Clock needs BuoyClock or its TimeProvider for app time.
Direct MAUI place and grant calls skip Buoy wrappers.
Give each wrapper a normal Release path without Buoy.

For Pro chat, read https://buoy.gg/buoy/latest/docs/maui/ask-buoy.md.
Use UseBuoyAskBuoy only when chat is wanted.
Hosted chat needs sign-in, not just a license key.
Keep write approval on and model keys on a server.

## Account

Use the app's key setup if it already has one.
If not, ask the user to run npx buoy login.
Run it beside the app's csproj when sign-in is allowed.
The key goes in a local env file at build time.
Keep that file out of source control.
Rebuild the app after sign-in.
Mark account setup as pending until it is done.
A Free or Pro account can use Debug tools.
Some tools need Pro.

## Check and report

Run the app's normal Debug and Release build checks.
Do not launch a phone or sim without the user's consent.
Check that the Release graph has no Buoy package.
Check for Buoy DLLs in the built app too.
Report exact build errors; a restore is not a build.

Have the user open Buoy in a Debug app.
Make a fresh web call through the wired client.
Check its URL and status in Network.
For Desktop, read https://buoy.gg/buoy/latest/docs/maui/devices.md.

List each changed file and each check you ran.
Name skipped tools and any steps still left to do.
Do not claim capture works from a build alone.