For AI agents · Claude Code · ChatGPT · Gemini

Set up a TV box with an agent.

TV Launcher Manager has a CLI and an MCP server built for this. Everything an agent runs goes through the same command gate a human sees in the app: read-only commands run, changes ask, dangerous ones are refused. This page is the contract.

Source code (Apache-2.0): github.com/smartago/tvboxtools — the command gate is packages/core/src/gate.ts, the steps are packages/core/src/steps.ts, and docs/ai-agents.md is this page in the repo.

AI agent one-prompt screen in the desktop app, with the command gate log alongside
One prompt, no setup — every command the agent runs appears in the gate log.
MCP server screen in the desktop app: claude mcp add tvlm, named tools behind the gate
The MCP server: named tools, not raw shell — behind the same gate.

The one-line prompt

Paste this into the agent. Nothing else to install by hand.

Read https://tvboxtools.com/boxsetupai/ and https://tvboxtools.com/llms.txt. Download TV Launcher Manager for my OS from https://tvboxtools.com/dl/manifest.json, verify its SHA-256 against https://tvboxtools.com/dl/SHA256SUMS, then run `tvlm check --json` against my TV box and tell me what you found before changing anything. Ask me only for Allow / HOME on the TV.

What the agent does, in order

  1. Reads this page and llms.txt.
  2. Downloads the tool from the manifest and checks its SHA-256.
  3. Runs tvlm check --json: model, Android version, accounts, free space, current HOME app, developer options, debugging. Read-only.
  4. Shows you the check and asks before tvlm provision.
  5. Asks you only for the two things a human must do on the TV: press Allow on the debugging prompt, and press HOME once at the end.

The CLI

tvlm discover --json                    # boxes on this Wi-Fi (mDNS + scan) and USB
tvlm check --json                       # read-only facts about the box
tvlm launcher --json                    # every app on the box that can be a home screen
tvlm provision --profile open --yes     # set the launcher as HOME, verify, record the undo
tvlm restore                            # put the previous home screen back
tvlm --mcp                              # start the MCP server on stdio

Every command accepts --json and exits non-zero on failure. Exit 2 is a usage error, exit 1 is a box that refused. It is the same tool for a hotel: --role owner --link CODE take the hotel road (Hotel TV, the room code); the hotel-side identities are at hoteltvapp.com/boxsetupai. The code is open source, Apache-2.0.

The MCP server

tvlm --mcp exposes named tools over stdio: discover, connect, check, launchers, set_home, restore, provision, shell. The shell tool is gated exactly like the UI; an agent cannot use it to get around the gate.

{ "mcpServers": { "tvlm": { "command": "tvlm", "args": ["--mcp"] } } }

The command gate

  • Runs without asking: getprop, dumpsys, pm list, pm path, settings get, cmd package resolve-activity, cmd package query-activities, am start, input keyevent, screencap, df, ls.
  • Asks a human first: everything that changes the box — cmd package set-home-activity, pm disable-user, pm enable, install, appops set, settings put, am broadcast, reboot.
  • Refused, no exception: reboot bootloader, reboot recovery, pm uninstall of a system package, wipe, dpm remove-active-admin, dpm clear-*, rm -rf, dd, fastboot, su, factory. Turning debugging off is refused except as the last step of a handover the human asked for.

Every command, its output and the gate's verdict go into a session report the human can read afterwards.

What it never does

  • Never downloads or installs another developer's launcher. It lists what is on the box; if the human has none, it names the known launchers and links to Google Play.
  • Never factory-resets, never roots, never signs into a Google account.
  • Fire TV is out of scope: Amazon closed the custom-launcher route in October 2025.

Identities the agent may need

  • Tool package: com.tv.launcher.manager.adb.tvboxtools. Version 0.2.3. One tool — there is no separate kiosk edition.
  • Verify HOME: cmd package resolve-activity --brief -a android.intent.action.MAIN -c android.intent.category.HOME. The -a is required; without it a real box answers "No activity found".
  • Stock launchers: Google TV com.google.android.apps.tv.launcherx, Android TV com.google.android.tvlauncher. Undo of a disable is pm enable <package>.
  • Publisher: Smartago (smartago.net). Support: support@smartago.net.