Quick Start

Get a TV app streaming to Buoy Desktop in under 2 minutes. There is no separate TV SDK — you install the same packages you would in any React Native app.

1. Install the core

2. Mount it headless

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

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

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

export default function App() {
  return (
    <>
      {/* your app */}
      <FloatingDevTools headless />  {/* 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 — no podspecs, no gradle edits, no prebuild — so this needs only a Metro restart.

3. Add the TV tools

Nothing else to wire — installed tools register themselves. 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: every focus move is credited to the direction that caused it, and focus that gets stuck, vanishes, or is never reached gets flagged.

Requirements

• react-native-tvos and the New Architecture (Fabric).
• Buoy adds no native dependencies — a Metro restart is the whole install step.
• Headless has no license entry UI. A Pro key can only arrive as the licenseKey prop. The desktop dashboard works at the free tier; the MCP server requires Pro.

More detail in Installation.