Free trial
Documentation
Getting Started
Fundamentals
Desktop App
AI Automation
Available Tools
docs

Quick Start

Add Buoy to a React web app and open the floating menu. The examples use Vite; any bundler that reads the browser export condition works. Frameworks has the setup for Next.js, React Router and TanStack Start.

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.

Let your coding agent install it
Read the prompt before you paste it
Install Buoy, the in-app devtools, in this React web project. Read the full instructions first: curl -fsSL https://buoy.gg/install-web.md Read the raw text, not a summary. If curl is unavailable, use any HTTP tool you have. Ask me to paste the document only if nothing can fetch it. Do the install yourself: inspect the repo, run the commands, edit the files. Do not hand me steps you can run. Work out the routine decisions from the repo: package manager, which app to target, the framework, where the early hook goes, where the host mounts, which Buoy tools match the dependencies already installed. If Buoy is already partly installed, repair and extend it; never add a second host, provider, or package set. When instructions conflict, follow this order: what I say here, then the document's rules about which packages exist and what needs my permission, then this project's own constraints, then the rest of the document, then your judgment. Ask me before: adding a dependency other than Buoy packages and react-native-web, showing Buoy outside development, opening a browser or creating an account, changing what a release build does beyond what the document specifies, or anything hard to undo. Do not commit. You are not done when the package installs. Run this project's existing typecheck and build; add no tooling. Then report what you installed and why, what you skipped and why, every file you changed, what you verified, and the exact steps I take in the browser to confirm the menu appears and captures a request.
The prompt asks your agent to inspect the project, choose matching tools and guide setup. Review its edits and verify the connection on your device.Read the setup instructions

To install by hand, follow the steps below.

1. Install

npm install @buoy-gg/core @buoy-gg/network @buoy-gg/storage react-native-web

For plain Markdown readers, the command is:

bash
npm install @buoy-gg/core @buoy-gg/network @buoy-gg/storage react-native-web

npm install @buoy-gg/core @buoy-gg/network @buoy-gg/storage react-native-web

Add other tools the same way. Your app doesn't need React Native or Expo.

2. Sign in

From the app directory:

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

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

In a Vite app, the CLI writes a dev token as VITE_BUOY_KEY in .env.development.local. Restart the dev server afterward. The token works in dev builds for 30 days. Keys still work too: see Sign in with Buoy.

3. Add the Vite plugin

ts
// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { buoy } from '@buoy-gg/core/vite';

export default defineConfig({
  plugins: [react(), buoy()],
});

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { buoy } from '@buoy-gg/core/vite';

export default defineConfig({
  plugins: [react(), buoy()],
});

The plugin finds the Buoy tools you installed and loads them. It also adds Buoy's early hook to index.html. The hook lets render tools see React. It also lets Network show calls from page load. Not using Vite? See Installation.

4. Mount Buoy

tsx
import { BuoyDevTools } from '@buoy-gg/core/web/auto';

export function App() {
  return (
    <>
      {/* your app */}
      <BuoyDevTools licenseKey={import.meta.env.VITE_BUOY_KEY} />
    </>
  );
}

import { BuoyDevTools } from '@buoy-gg/core/web/auto';

export function App() {
  return (
    <>
      {/* your app */}
      <BuoyDevTools licenseKey={import.meta.env.VITE_BUOY_KEY} />
    </>
  );
}

BuoyDevTools shows Buoy in dev builds. Release builds don't load Buoy's tools or menu. They still load the early hook. It stays off unless Buoy ran in that browser in the last week. Mount it inside the providers your tools read. Examples are QueryClientProvider and the Redux Provider.

Reload the page. The floating menu appears, and Network lists the page's requests, including the ones made before Buoy loaded.

5. Connect Buoy Desktop (optional)

bash
npm install @buoy-gg/external-sync

npm install @buoy-gg/external-sync

The plugin adds it like any other tool. Open Buoy Desktop and the tab appears in the device switcher.

More detail, including the setup for each tool, is in Installation.

Edit on GitHub
Overview
Installation