React Native TV DevTools Setup — install Buoy on Apple TV & Android TV

Connect a React Native TV app to Buoy Desktop, then inspect remote input and focus. Buoy uses the same JavaScript packages as its phone integration.

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 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

To install by hand, follow the steps below.

1. Install the core

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.

2. Mount it headless

tsx

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

export default function App() {
  return (
    <>
      {/* your app */}
      <FloatingDevTools headless licenseKey={process.env.EXPO_PUBLIC_BUOY_KEY} />  {/* TV apps run headless — no bubble */}
    </>
  );
}

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

export default function App() {
  return (
    <>
      {/* your app */}
      <FloatingDevTools headless licenseKey={process.env.EXPO_PUBLIC_BUOY_KEY} />  {/* TV apps run headless — no bubble */}
    </>
  );
}

headless mounts every installed tool's sync adapter plus the route, console and store instrumentation, and renders no on-device UI at all — no bubble, no dial, no overlays. It is not a TV-specific flag; it is the same mode shipped for field builds where only the desktop should see the session. See Overview for why that is the right call on TV rather than a compromise.

Buoy adds no native dependencies to a TV app. Restart Metro after adding the packages. Follow the requirements of any other dependencies you add.

3. Add the TV tools

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

The TV tools register when installed. Other tools may need app-specific configuration. Add any other tool the same way (@buoy-gg/network, @buoy-gg/storage, …) and it appears in the desktop dashboard.

4. Connect Buoy Desktop

Open Buoy Desktop and your TV appears in the device switcher next to your phones.

An Android TV emulator needs the broker port forwarded once per device:

adb -s <serial> reverse tcp:42831 tcp:42831

adb -s <serial> reverse tcp:42831 tcp:42831

Pass -s <serial> explicitly — a physical phone is often attached at the same time, and adb will otherwise pick the wrong one.

An Apple TV simulator connects on its own.

5. Press the remote from your desktop

Open TV Remote in Buoy Desktop, pair the device with an injection target, and press. Presses go through the platform's real input pipeline, so they move focus exactly like a physical remote.

Injection needs adb on your PATH (Android SDK platform-tools) and, for the 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

Without it the Apple TV lane is disabled and the panel says so. A retail Apple TV can be recorded but not driven — see the target table in the Overview.

Then open Focus and drive the app: reported focus moves can be compared with observed direction inputs. Review flags against actual device behavior.

Requirements

react-native-tvos and the New Architecture (Fabric).
Restart Metro after adding JavaScript tools. Your TV runtime and host input tools have separate setup requirements.
Headless has no license entry UI. Configure your Free or Pro account key before mounting the headless tools. The desktop dashboard works at the free tier; the basic MCP server is free. Pro adds the full MCP.

More detail in Installation.

Quick Start