docs

Sign in with Buoy

Sign in with Buoy

sign in with a code, in 81 seconds

Your Buoy account turns on Buoy, the same way a key does. You sign in once on each computer, browser or site.

Your dev builds

Run this in your app's folder:

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

Your browser opens buoy.gg. Click Allow. The CLI then writes a dev token to your project. It uses the name a key used to have.

A dev token only works in dev builds and sims. If one ends up in a shipped app, it opens nothing there. It lasts 30 days. After that, Buoy asks you to run buoy login again.

Where the token goes depends on your project:

ProjectWhere it goesWhat you do next
ExpoEXPO_PUBLIC_BUOY_KEY in .env.development.localNothing. Buoy reads it in dev builds.
Next.jsNEXT_PUBLIC_BUOY_KEY in .env.development.localRestart next dev. Buoy reads it.
ViteVITE_BUOY_KEY in .env.development.localBuoyDevTools, FloatingDevTools from @buoy-gg/core/web, Vue and Solid read it.
AngularBUOY_KEY in .env.development.local and src/environments/buoy.tsRestart ng serve. The builder reads it.
.NET MAUIBUOY_KEY in .env.development.localRebuild. The build reads it.
FlutterBUOY_KEY in .env.localRun with --dart-define-from-file=.env.local.
XcodeBUOY_LICENSE_KEY in .env.localAdd it to your Run scheme.
Androidbuoy.key in local.propertiesPass it in as BuildConfig.BUOY_LICENSE_KEY.
OtherBUOY_KEY in .env.localPass it in with your own env loader.

The CLI prints the next step for your project too.

Two more commands:

bash
npx --package=@buoy-gg/core buoy whoami   # are you signed in?
npx --package=@buoy-gg/core buoy logout   # sign this computer out
npx --package=@buoy-gg/core buoy whoami   # are you signed in?
npx --package=@buoy-gg/core buoy logout   # sign this computer out

whoami checks two things. It tells you if this computer is signed in. It also tells you which env file holds a key for this project.

If login can't reach buoy.gg

Some VPNs and proxies let your browser reach buoy.gg but block Node. Then buoy login says it could not reach buoy.gg. Your browser still signs in the project. The CLI writes your account key to your env file. In Expo, a Pro or Business key goes in .env.local. In Vite and Next.js, every key goes in .env.development.local, so it stays out of your live site.

This computer stays signed out, so whoami says so. It also names the file that has the key. To sign in this computer too, run buoy login again when Node can reach buoy.gg.

Desktop and the MCP

In Buoy Desktop, click Sign in with buoy.gg. Desktop keeps your sign-in in your computer's keychain, and you stay in after restarts. Sign out ends it on buoy.gg too. Your settings follow you to Desktop as well.

The MCP uses the sign-in from buoy login. You don't need a key in your project for the MCP. If this computer is not signed in, the MCP looks for a key in the env files of the folder it runs in. It checks that key with buoy.gg, so Node must be able to reach buoy.gg.

Your live site

A live site can turn on Buoy for your own admins and testers, with no key in the build.

  1. Add your site at buoy.gg/dashboard/sites. Use its address, like https://app.example.com.
  2. Add signIn to FloatingDevTools:
tsx
<FloatingDevTools modules={modules} signIn />
<FloatingDevTools modules={modules} signIn />

A "Sign in to Buoy" button shows in the corner. It opens a buoy.gg window that asks to let your site use Buoy. After that, Buoy opens, and it stays open after reloads.

Only show FloatingDevTools to your own people. Your app decides who sees it, the same as before.

Buoy on a live site needs a Pro or Business plan. A free account sees a note that asks for a plan.

Phones and test builds

A phone app can't open a sign-in window. So it shows a code instead, as a QR code and as text. Use it for TestFlight, QA and store builds, where no key is in the app.

  1. Add your app at buoy.gg/dashboard/sites. Type app: and then its id, like app:com.acme.shop. That is the iOS bundle id or the Android package.
  2. Add signIn to FloatingDevTools:
tsx
<FloatingDevTools signIn />
<FloatingDevTools signIn />

Tap "Sign in" in the corner. Scan the QR code with any phone that is signed in to buoy.gg. Or go to buoy.gg/activate and type the code. Check the code, then tap Allow. Buoy opens in the app a few seconds later.

Buoy reads the app id from your Expo config. If it can't, pass it in: signIn={{ appId: "com.acme.shop" }}.

A code lasts 10 minutes and works once. Only allow a code shown on a device in your hand. If someone sends you a code, don't type it in.

The same plan rule applies: Buoy in a test or store build needs Pro or Business.

Flutter

dart
BuoyDevTools(
  signIn: const BuoySignIn(appId: 'com.acme.shop'),
  child: child,
)
BuoyDevTools(
  signIn: const BuoySignIn(appId: 'com.acme.shop'),
  child: child,
)

On Flutter, Buoy runs in debug builds. So this lets you skip buoy login there.

Swift

swift
var config = BuoyConfig()
config.signIn = BuoySignInConfig()
Buoy.start(config)
var config = BuoyConfig()
config.signIn = BuoySignInConfig()
Buoy.start(config)

Swift reads the app id from your bundle id.

Android

kotlin
Buoy.start(this, BuoyConfig(signIn = BuoySignInConfig()))
Buoy.start(this, BuoyConfig(signIn = BuoySignInConfig()))

Android reads the app id from your package name.

.NET MAUI

csharp
builder.UseBuoy(options =>
{
    options.SignIn = new BuoySignInOptions();
});
builder.UseBuoy(options =>
{
    options.SignIn = new BuoySignInOptions();
});

MAUI reads the app id from your bundle id or package name.

How long you stay in

You stay signed in as long as you use Buoy at least once every 60 days. Buoy renews your sign-in in the background.

With no internet, Buoy keeps working for 7 days. Then the tools lock until it can check in.

If someone leaves your team, or you remove a site, Buoy stops for them within 12 hours.

Your settings follow you

Sign in on two devices. Change a setting on one, and it shows up on the other. This works with a sign-in or a dev token. Plain keys and bot keys don't sync.

Only your settings move. Web calls you saved and other data Buoy caught stay on the device.

A new setting goes out a few seconds after you change it. Other devices get it when they start, or within 15 minutes.

Teams

Business teams are run from the Team page. A team admin can:

  • invite people by email, up to the seats you bought;
  • give each person a role, like dev or qa;
  • pick which Buoy tools each role sees;
  • see and remove the scenarios people shared with the team;
  • remove people, which frees their seat;
  • list the team's live sites, which every member then uses;
  • list web calls to hide for the whole team;
  • list React Query queries to hide, or the only ones to show.

Team lists add to each person's own lists. In the app, team items show a TEAM badge.

A role can see all tools, or just the tools on its list. A hidden tool only leaves the menu. It is not locked. Your app's own tools always show. When Buoy adds a new tool, it starts off for a role with a list.

People get a tool change at their next refresh, within 12 hours. To get it now, sign out and sign back in.

Keys still work

You don't have to switch. A key you already use keeps working everywhere, and keys are staying. Use one if you'd rather not sign in, or for a build where no one can sign in.

One warning: don't build a key into a live website. A site's code is public, so anyone can copy the key and use your plan. For a live site, use sign-in. No key is in the build then.

To change accounts on a phone, open the dial's settings and go to the Pro tab. Tap Sign out. This ends your sign-in on this device, and it turns off any key too. A key built into the app stays off, even after a restart. Then sign in with a code, or tap "Use the Buoy key again". The code sign-in needs app: plus your app's id at buoy.gg/dashboard/sites.

Keys for bots and CI

Bots and CI can't click a sign-in button. On the Team page, a team admin can make a bot key. It starts with bsk1_. You see it once, so copy it right away.

Put the bot key where a license key goes, such as a CI secret that sets EXPO_PUBLIC_BUOY_KEY. Buoy trades it for a pass that lasts a day. Delete the key on the Team page, and the bot stops within a day.