Install React Native TV DevTools — Buoy setup for Apple TV & Android TV

Buoy on TV is the ordinary React Native install with one prop changed. This page is the complete version of Quick Start.

Requirements


React Native	`react-native-tvos` (the TV fork)
Architecture	New Architecture / Fabric
App type	Expo TV (`@react-native-tvos/config-tv`) or bare RN TV — both verified
Native deps added by Buoy	None — no podspecs, no gradle changes, no prebuild
Host tooling	`adb` for Android TV; `idb` for the Apple TV simulator (remote injection only)

Expo Go cannot run a TV app at all — TV is always a prebuild + expo run:* app. That is a property of TV, not of Buoy.

Install with your agent

Paste the prompt into Claude Code, Cursor or Codex. Your agent reads your app and picks the tools. Review its changes before you commit them.

Let your coding agent install itClaude Code · Cursor · Codex

Read the prompt before you paste it

Install Buoy, the in-app devtools, in this React Native TV project. Read the full instructions first: curl -fsSL https://buoy.gg/install-tv.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, Expo TV or bare, where the headless mount goes, which Buoy tools match the dependencies already installed. If Buoy is already partly installed, repair and extend it; never add a second mount, 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 native dependency, 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; 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 with Buoy Desktop to confirm the TV connects 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

Packages

Install the core, then any tools you want. Installed tools register themselves; there is no list to maintain.

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

For plain Markdown readers, the command is:

bash

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

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

Configure a Free or Pro key with npx --package=@buoy-gg/core buoy login. The examples use Expo's EXPO_PUBLIC_BUOY_KEY; React Native CLI apps must supply the key through their own environment configuration.

The two TV-specific tools:

npm install @buoy-gg/tv-remote @buoy-gg/focus-inspector

Everything else installs exactly as it does on a phone — Network, Storage, Console, Env, Routes, Events, React Query, Redux, Zustand, Jotai are all device-verified on both TV platforms.

Mounting

tsx

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

export default function App() {
  return (
    <>
      {/* your app */}
      <FloatingDevTools
        headless
        licenseKey={process.env.EXPO_PUBLIC_BUOY_KEY}
        externalSync={{ deviceName: "Living Room Apple TV" }}
      />
    </>
  );
}

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

export default function App() {
  return (
    <>
      {/* your app */}
      <FloatingDevTools
        headless
        licenseKey={process.env.EXPO_PUBLIC_BUOY_KEY}
        externalSync={{ deviceName: "Living Room Apple TV" }}
      />
    </>
  );
}

headless is required on TV in practice: without it the floating bubble renders, and on Android TV its focusable views join your app's D-pad focus order. See Overview.

deviceName is what shows in Buoy Desktop's switcher. Give each TV a distinct one — an Apple TV simulator and an Android TV emulator running the same app are otherwise hard to tell apart.

Connecting to the desktop

Device	What it needs
Apple TV simulator	Nothing — it connects on its own.
Android TV emulator	`adb -s <serial> reverse tcp:42831 tcp:42831`, once per boot.
Physical TV device	A `socketURL` pointing at your machine's LAN address.

Pass -s <serial> to adb explicitly. A physical phone is often attached alongside the emulator, and an unqualified adb reverse forwards the wrong device.

Host tooling for the TV Remote

Replay is injected from your machine, so the binaries have to be findable:

Android — adb, part of the Android SDK platform-tools.

Apple TV simulator — idb, which does not ship with Xcode:

brew tap facebook/fb && brew install idb-companion
pipx install fb-idb

brew tap facebook/fb && brew install idb-companion
pipx install fb-idb

Buoy looks for both on your PATH and in the usual install locations, so the packaged desktop app finds them even though a GUI app inherits a minimal PATH. If idb is missing, the Apple TV lane is disabled and the panel says so rather than failing silently.

Recording needs none of this — capture is pure JavaScript and works on retail hardware.

License keys

A verified Free or Pro account is required. Desktop is free to use. Production access requires Pro. Free has the basic MCP, and Pro adds the full MCP.

Headless has no license entry UI — there is no on-device screen to type into. On TV a key can be supplied through initialization or the licenseKey prop, typically from your environment configuration. The desktop dashboard works at the free tier; the MCP server needs an account and will refuse a TV device with no admitted account.

Don't have a key yet? Grab one at buoy.gg/pricing.

Installation