@buoy-gg/external-sync

Connect a React Native app's Buoy tools to Buoy Desktop or MCP. This package provides the device-side socket connection, adapter synchronization, and remote-action handling. Most apps configure it through FloatingDevTools from @buoy-gg/core.

Capacitor / Ionic (Beta) uses this package through /web. See the setup guide for steps and limits.

Install

npm install @buoy-gg/core @buoy-gg/external-sync @buoy-gg/network

Account setup

Start in a development build. You need a Free or Pro Buoy account. Sign in from your app's folder:

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

Your browser opens buoy.gg. Click Allow. The CLI then writes a dev token. It works in dev builds for 30 days.

On Expo, the token goes in .env.development.local. Buoy reads it by itself in dev builds. You can also pass it in yourself:

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

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

On React Native CLI, the token goes in .env.local as BUOY_KEY. React Native does not load that file by itself. Pass the token in with your app's own env setup. Keep the menu inside the providers used by your app. Restart the development server after installing packages. See the Quick Start for the complete root component.

Connect your app

Mount the menu in your existing root component after account initialization:

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

<FloatingDevTools />;

Open Desktop and sign in. In development, the app normally derives the broker address from Metro. If your network or Expo tunnel setup needs an explicit address, replace the menu above with:

<FloatingDevTools
  externalSync={{ socketURL: "http://YOUR_COMPUTER_LAN_IP:42831" }}
/>;

socketURL has an uppercase URL. The device must be able to reach that address; a Metro tunnel does not automatically expose the broker. For Android over USB, follow the port-forwarding instructions in the Desktop guide.

Select the device in Desktop, trigger a fresh HTTP request in the app, and check that it appears in Network. If no device appears, check both account states, the broker address, and network connectivity. If the device appears but the panel is empty, check the tool's installation and capture path.

Headless and release builds

<FloatingDevTools headless /> keeps the connection integration without the floating menu. It still needs account access and configured tools.

Release sync is disabled by default. For an authorized internal release build with Pro, explicitly configure it:

<FloatingDevTools
  headless
  externalSync={{
    enableInRelease: true,
    socketURL: "http://YOUR_COMPUTER_LAN_IP:42831",
  }}
/>;

Apply your app's authorization checks before mounting this integration. Enabling sync does not make development-only tools work in release builds.

Custom integrations

The public exports include useExternalSyncSocket, useExternalSync, ToolSyncAdapter, URL helpers, sync-status subscriptions, and crash-flush helpers. An adapter supplies snapshots, subscriptions, and named actions. The bridge subscribes according to dashboard watch state and throttles updates; it also enforces device account admission.

Prefer the core integration unless you are building a custom host. A direct hook integration must manage socket and device identity, account initialization, adapter lifecycle, and action authorization. Use the exported option types and custom-tool guide.

Desktop and MCP

React Native connections require @buoy-gg/external-sync. Follow the Desktop connection guide, sign in to Desktop separately, and confirm the selected device. MCP uses the sign-in from buoy login on your computer. Free has the basic MCP. Pro adds the full MCP.

Device data can travel over your LAN to the configured broker. Account validation makes network requests. See Telemetry for data-flow details.