Quick Start

Get the in-app menu running in under 2 minutes — then reach the same tools from your desktop or your AI agent.

1. Install the core

2. Add to your app

Drop FloatingDevTools at the root of your app:

import { FloatingDevTools } from "@buoy-gg/core";

export default function App() {
  return (
    <>
      <YourApp />
      <FloatingDevTools />
    </>
  );
}

import { FloatingDevTools } from "@buoy-gg/core";

export default function App() {
  return (
    <>
      <YourApp />
      <FloatingDevTools />
    </>
  );
}

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

Every tool works with no key at all, capped at about five entries each — enough to see what they do. A free key raises that to 25 per tool and includes Pro free every weekend; Pro unlocks everything: production builds, the MCP server, Ask Buoy, and unlimited capture. See pricing.

Grab your key — free or paid, same command:

npx buoy login

npx buoy login

Run this from a project where @buoy-gg/core is installed — npx resolves the command from your own node_modules. If npx tries to download something instead (there is an unrelated buoy package on npm), name the package explicitly:

bash

Copy

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

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

It signs you in, writes the key to .env.local, and gitignores it. Then:

Buoy.init({ licenseKey: process.env.EXPO_PUBLIC_BUOY_KEY });

Buoy.init({ licenseKey: process.env.EXPO_PUBLIC_BUOY_KEY });

See Installation for the details.

3. Add tools

Install any tool package — it automatically appears in the menu. No wiring, no config.

That's it. Open the menu, tap Network, and you're watching every API call in real-time.

Zustand stores

If you use Zustand, pass your stores directly via zustandStores:

import { FloatingDevTools } from "@buoy-gg/core";
import { useAuthStore } from "./stores/auth";
import { useCartStore } from "./stores/cart";

const stores = {
  authStore: useAuthStore,
  cartStore: useCartStore,
};

return (
  <FloatingDevTools zustandStores={stores} />
);

import { FloatingDevTools } from "@buoy-gg/core";
import { useAuthStore } from "./stores/auth";
import { useCartStore } from "./stores/cart";

const stores = {
  authStore: useAuthStore,
  cartStore: useCartStore,
};

return (
  <FloatingDevTools zustandStores={stores} />
);

Jotai atoms

If you use Jotai, call watchAtoms once at module scope with your store and a named map of atoms:

import { getDefaultStore } from "jotai";
import { watchAtoms } from "@buoy-gg/jotai";
import { authAtom } from "./atoms/auth";
import { cartAtom } from "./atoms/cart";

watchAtoms(getDefaultStore(), {
  authAtom,
  cartAtom,
});

import { getDefaultStore } from "jotai";
import { watchAtoms } from "@buoy-gg/jotai";
import { authAtom } from "./atoms/auth";
import { cartAtom } from "./atoms/cart";

watchAtoms(getDefaultStore(), {
  authAtom,
  cartAtom,
});

No wrappers, no middleware. Registered atoms automatically appear in the Jotai tool inside your FloatingDevTools menu.

Available tools

Install what you need. Skip what you don't.

Control who sees devtools

Only show devtools to specific users — admins, QA, internal team members, or whoever your business needs:

import { FloatingDevTools } from "@buoy-gg/core";

export default function App() {
  const { user } = useAuth();

  // Only render for internal users, admins, or QA
  const showDevTools =
    user?.role === "admin" ||
    user?.role === "qa" ||
    user?.email?.endsWith("@yourcompany.com");

  return (
    <>
      <YourApp />
      {showDevTools && (
        <FloatingDevTools
          licenseKey="YOUR_LICENSE_KEY"
          userRole={user?.role}
        />
      )}
    </>
  );
}

import { FloatingDevTools } from "@buoy-gg/core";

export default function App() {
  const { user } = useAuth();

  // Only render for internal users, admins, or QA
  const showDevTools =
    user?.role === "admin" ||
    user?.role === "qa" ||
    user?.email?.endsWith("@yourcompany.com");

  return (
    <>
      <YourApp />
      {showDevTools && (
        <FloatingDevTools
          licenseKey="YOUR_LICENSE_KEY"
          userRole={user?.role}
        />
      )}
    </>
  );
}

Or keep it available for everyone — your QA and support teams will thank you.

Take it further

The tools you just installed aren't only in the floating menu — reach the same live app three more ways:

• Buoy Desktop — mirror every tool to a full dashboard on macOS, Windows, or Linux, with a live performance HUD and multi-device switching.
• Ask Buoy (beta) — an in-app chat that drives every tool you just installed, so QA, support and product can trigger states and read app data without touching a tool or a ticket. Point it at your own model endpoint; Buoy never holds a key.
• 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 and Ask Buoy are Pro features. Desktop and MCP talk to your app through one extra package — npm install @buoy-gg/external-sync in the app and restart Metro with --clear — and from there the connection is automatic, with no URLs to configure (physical devices included). Ask Buoy needs no broker at all: it runs on the device and talks only to the endpoint you give it.

What's next

• FloatingDevTools — Core component reference
• Buoy Desktop — The full desktop dashboard
• Ask Buoy — Drive every tool from an in-app chat
• AI / MCP Server — Drive your app from your AI editor
• Custom Tools — Build your own debugging tools

FAQ

Do I need a license key to use React Buoy?

No — every tool works without one, capped at about five entries each. A free key raises that to 25 per tool and includes Pro free every weekend. Pro unlocks everything: production builds, the MCP server, Ask Buoy, and unlimited capture.

The fastest way to get either is npx buoy login. A free key needs no card and takes about thirty seconds.

Does Buoy phone home?

Once a day, in development only, it sends a random install id, the Buoy version, your platform, and your license tier. Never your project, your app, or anything from the tools — that data never leaves your machine. Turn it off with Buoy.init({ telemetry: false }). Full details: Telemetry.

How do I add a tool to the menu?

Install the package. Auto-discovery finds it and the tool appears in the floating menu with no wiring and no config — npm install @buoy-gg/network, open the menu, tap Network.

Will the devtools ship to my users?

The menu only renders where you mount FloatingDevTools, and desktop sync is off whenever __DEV__ is false unless you opt in explicitly with a Pro license — so a shipped app never dials a broker on a customer's phone.