Setting Up ADB Shell Permissions on Sideloaded Android TV

Updated 2026-10-31

Why sideloading Android TV firmware needs ADB shell access

Most Android TV boxes sold in the US or Europe ship with locked-down firmware images that don’t include developer options. To customize the box—install custom launchers, tweak overlay behavior, or debug the UI—you need ADB shell access. On official builds the button exists; on sideloaded firmware the developer option is hidden behind a system property guard, so the first step is always getting the right shell permissions without bricking the box.

On sideloaded Android TV devices the shell permission is often denied to the user account because the boot image ships without the sideload signing key that authorizes elevated ADB use. Switching to a locally built launcher like CleanYourTV means the standard path to the developer menu is no longer available either, so the fix is to wrap the boot image in a signed package that includes the necessary permission flags.

Preparing the environment before flashing

Before you touch anything, make sure your host machine has the correct Android TV SDK and a tinned ADB binary that supports pm grant. You also need a working Linux or Windows shell environment with USB OTG support, since most sideloading flows rely on a physical connection rather than the Google Play Wi-Fi setup used on phones. Verify the TV’s media transfer protocol with adb -s /dev/adb once connected; if the device doesn’t respond, check the USB cable and the HDMI port.

Create a minimal signed wrapper APK containing a small Java class that calls Runtime.getRuntime().exec("sh") or launches a shell via execDirect, then sign it with the same keystore you’d use for production OTA updates. The wrapper’s purpose is simply to unlock the developer menu; it won’t run any custom logic. Build it with jpackage -t app -k android.app.PermissionManager ... to embed the required permission declarations in the manifest so the OS accepts the elevation without user prompts.

• adb version: Android SDK Platform-Tools 335.0.0
• Wrapper APK size: ~8 MB (signed, stripped of unused resources)
• TV firmware: Android TV 12 (QKMT23) or later

Granting yourself ADB shell permission on the box

Once the wrapper APK is flashed to the TV’s internal storage and the device reboots into developer mode, log in with your Google account and navigate to Settings → About → System → Developer options. The developer options section will now expose “ADB shell” and “Apps with network access.” Tap each one and wait for the confirmation dialog—this is the point where the signed wrapper adds its signature entry to the device’s privileged partition.

After the confirmations, connect the TV over USB and run adb shell. The command getprop ro.debug.adb.shell should return 1, which signals that the shell has elevated privileges. If it returns 0 or you get an “Permission denied” error, re-run the wrapper APK’s launch script and check whether the device’s shell permission file changed. On some stock Android TV builds the permission file is written to /data/system/root/ after the wrapper finishes installing; a quick ls -la /data/system/root/ will show shell as readable only by root, while your user account remains blocked unless you switch to root via su using the wrapper’s credential.

Testing and common pitfalls

After confirmation, test the shell by running service shell and entering am start -a android.settings.Settings. If the shell opens but adb commands fail, the wrapper likely didn’t persist—the wrapper must write a shell permission entry to the persistent state store. Re-flash the wrapper with --action=unlock if your build tool supports it, and double-check that the manifest contains <uses-permission android:name="android.permission.ADB_SHELL" />.

Two issues surface frequently:

• The lock screen password is required to grant shell access; some users forget that the TV’s screen lock must be active for the developer menu to appear.
• The TV firmware has a hard-coded check that rejects any unsigned wrapper before it reaches the development menu—so always test on a non-production build first.

When you’re ready, launch CleanYourTV through the unlocked shell and verify that the custom launcher starts without crashing. If it hangs on startup, clear the com.cleanyourtv.shell shared preference file in /data/data/com.cleanyourtv.shell/.

Where to find help and keep updating the TV

The official Android TV developer forums and the CleanYourTV GitHub wiki are the best places to look for firmware-specific instructions. When a new TV firmware version ships, the permission model sometimes shifts: some 13th-gen models moved the requirement to a separate “developer unlock” toggle that appears only after the first boot after firmware flash. Keep a backup image of the original firmware, and if you encounter a permanent permission wall, post the exact log output from logcat | grep -E 'adb|shell' to the community thread for targeted fixes.

Related reading: more Android TV notes