Put shangOS on your TV

Before you start

You need an Android TV or Google TV on Android 12 or newer, a computer on the same Wi-Fi or network cable, and the TV remote. It takes about five minutes. It needs no root and replaces no firmware.

Not for phones and tablets. Not tested on Fire TV.

1. Turn on debugging on the TV

1. Become a developer

   Find the build entry for your TV in the table below, and press OK on it seven times until a message says You are now a developer.

   Menu names change between firmware versions. If yours differ, search Settings for “Build” and “Developer options”.

   Your device	Turn on Developer options	Then open
   Google TV Streamer, Chromecast with Google TV, onn., TCL, Hisense, Sony BRAVIA (Google TV)	Settings, System, About, press Android TV OS build 7 times	Settings, System, Developer options
   Sony BRAVIA (older Android TV), Philips, Sharp	Settings, Device Preferences, About, press Build 7 times	Settings, Device Preferences, Developer options
   Xiaomi Mi Box S, Mi TV Stick, Xiaomi TV	Settings, Device Preferences, About, press Build 7 times	Settings, Device Preferences, Developer options
   NVIDIA Shield TV	Settings, Device Preferences, About, press Build 7 times	Settings, Device Preferences, Developer options

2. Switch debugging on

   In Developer options, turn on USB debugging. Some TVs call it Network debugging. On Android 11 and newer you may see Wireless debugging instead; see pairing below.

3. Allow your computer

   The first time the computer connects, the TV asks Allow USB debugging?. Choose Always allow from this computer and press OK. Look at the TV screen, not the computer.

4. Find the TV’s address (optional)

   The wizard usually finds the TV by itself. If it cannot, note the IP address under Settings, Network & Internet, then your connection (for example 192.168.1.50).

2. Run the setup wizard

Open a terminal (macOS, Linux) or PowerShell (Windows), and run the line for your computer. No administrator rights are needed.

$ curl -fsSL https://shangos.madusha.dev/setup.sh | bash

$ curl -fsSL https://shangos.madusha.dev/setup.sh | bash

PS> [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12; iex ((New-Object Net.WebClient).DownloadString('https://shangos.madusha.dev/setup.ps1'))

The wizard is five short steps. Move with the arrow keys (or j/k), choose with Enter, switch options with Space, go back with Esc, quit with q.

1. TV

   Lists TVs adb already knows, TVs announcing Wireless debugging on your network, and addresses you saved. Or type an address, or pair with a code. It checks the TV runs Android 12 or newer.

2. Build

   Standard, or Offline which has no internet permission at all (no weather, no remote posters).

3. Options

   Optional permissions, making it the home screen, a faster compile, the screen saver, and ad and tracker blocking (off unless you tick it).

4. Review

   Shows the exact commands, then asks once.

5. Install

   Downloads the release from GitHub, checks its SHA-256 against the published SHA256SUMS, installs it, and applies your options. Every command that changes the TV is printed first, on a line starting with +.

Without a menu

For scripts and unattended installs, pass options. --yes (-Yes on Windows) takes every default and asks nothing.

$ curl -fsSL https://shangos.madusha.dev/setup.sh | bash -s -- --tv 192.168.1.50:5555 --variant offline --yes

$ curl -fsSL https://shangos.madusha.dev/setup.sh | bash -s -- --tv 192.168.1.50:5555 --variant offline --yes

PS> & ([scriptblock]::Create((New-Object Net.WebClient).DownloadString('https://shangos.madusha.dev/setup.ps1'))) -Tv 192.168.1.50:5555 -Variant offline -Yes

$ curl -fsSL -o setup.sh https://shangos.madusha.dev/setup.sh
$ less setup.sh
$ bash setup.sh

$ curl -fsSL -o setup.sh https://shangos.madusha.dev/setup.sh
$ less setup.sh
$ bash setup.sh

PS> (New-Object Net.WebClient).DownloadString('https://shangos.madusha.dev/setup.ps1') | Set-Content setup.ps1
PS> notepad setup.ps1
PS> powershell -ExecutionPolicy Bypass -File .\setup.ps1

No adb on your computer? The wizard offers to install it with your package manager (Homebrew, apt, dnf, pacman, zypper, or on Windows winget, Scoop or Chocolatey) and shows the command first. Or get platform-tools from Google.

Optional: block ads and trackers on the whole TV

shangOS itself shows no ads, but your other apps can. This optional step sets the TV’s Private DNS (an Android setting since Android 9) to a server that refuses known ad and tracker domains. It applies to every app that uses the TV’s normal DNS, and it does not touch shangOS.

$ curl -fsSL https://shangos.madusha.dev/setup.sh | bash -s -- --dns adguard

$ curl -fsSL https://shangos.madusha.dev/setup.sh | bash -s -- --dns off

$ curl -fsSL https://shangos.madusha.dev/setup.sh | bash -s -- --dns adguard

$ curl -fsSL https://shangos.madusha.dev/setup.sh | bash -s -- --dns off

PS> & ([scriptblock]::Create((New-Object Net.WebClient).DownloadString('https://shangos.madusha.dev/setup.ps1'))) -Dns adguard

PS> & ([scriptblock]::Create((New-Object Net.WebClient).DownloadString('https://shangos.madusha.dev/setup.ps1'))) -Dns off

Or tick Block ads and trackers in the wizard’s options, or pass --block-ads (-BlockAds) when installing. Choose Use my own DNS hostname in the wizard’s menu for a NextDNS profile, your own AdGuard Home or a Pi-hole that speaks DNS-over-TLS. The wizard checks that the TV can still look up names afterwards, and puts the old setting back if it cannot.

By hand

$ adb shell settings put global private_dns_specifier dns.adguard-dns.com
$ adb shell settings put global private_dns_mode hostname

$ adb shell settings put global private_dns_mode opportunistic

What to know first

TVs that show a pairing code

Newer Google TV builds can use Wireless debugging, which asks for a one-time pairing first.

1. Open the pairing box

   Developer options, Wireless debugging, Pair device with pairing code. The TV shows an address with a port, and a six-digit code. Keep that box open.

2. Pair

   In the wizard choose Pair with a code, or run it yourself:

   macOSLinuxWindows

   macOS

   TerminalCopy

   $ adb pair 192.168.1.50:37123

   Linux

   TerminalCopy

   $ adb pair 192.168.1.50:37123

   Windows

   PowerShellCopy

   PS> adb pair 192.168.1.50:37123

   Type the six-digit code when asked.

3. Connect

   Close the box. The main Wireless debugging screen shows a different port. Use that one: adb connect 192.168.1.50:41234, or pick the TV in the wizard (it appears under “Found on your network”).

Do it by hand with adb

The wizard runs exactly these. Replace the address and the file name with yours.

# 1. connect, and accept the prompt on the TV
$ adb connect 192.168.1.50:5555
# 2. install the signed release
$ adb install -r shangos-v0.4.0-release.apk
# 3. make it the home screen
$ adb shell cmd package set-home-activity --user 0 dev.madusha.shangos/.MainActivity

Press Home on the remote. If the TV still opens its own launcher, that is normal on some Google TVs. Open shangOS from the app row, or choose “Always” if the TV asks which home to use. Do not switch the TV’s own home or setup app off unless you have read the warning below: on some Google TVs the TV then cannot start.

Optional permissions for Up Next, Now Playing and recent apps:

$ adb shell pm grant dev.madusha.shangos android.permission.READ_TV_LISTINGS
$ adb shell cmd notification allow_listener dev.madusha.shangos/dev.madusha.shangos.MediaListener
$ adb shell appops set dev.madusha.shangos GET_USAGE_STATS allow

Undo everything

Run the wizard and choose Remove shangOS, or pass the uninstall option:

$ curl -fsSL https://shangos.madusha.dev/setup.sh | bash -s -- --uninstall

$ curl -fsSL https://shangos.madusha.dev/setup.sh | bash -s -- --uninstall

PS> & ([scriptblock]::Create((New-Object Net.WebClient).DownloadString('https://shangos.madusha.dev/setup.ps1'))) -Uninstall

By hand, switch your TV’s launcher back on before removing shangOS, so the TV always has a home screen:

$ adb shell pm enable --user 0 com.google.android.tvlauncher
# or com.google.android.apps.tv.launcherx on newer Google TV builds
$ adb uninstall dev.madusha.shangos

If your TV loops after a restart

If your TV is looping now:

1. Switch the TV off at the wall

   Leave it off for 10 to 15 minutes, then switch it on again. Have your computer ready.

2. Switch them back on as soon as the TV answers

   Each loop gives a short window. Keep trying until the commands go through:

   adbCopy

   $ adb connect 192.168.1.50:5555
   $ adb shell pm enable com.google.android.apps.tv.launcherx
   $ adb shell pm enable com.google.android.tungsten.setupwraith
   $ adb shell pm enable com.google.android.tvlauncher

   Some of these are not on your TV; the error for those is harmless.

3. Then run the wizard again

   The current version leaves them on. If you set shangOS up with an older version and the TV is not looping, run the wizard once before the next restart: it switches them back on by itself.

If shangOS itself crashes twice within five minutes, it stands aside and lets the TV’s own home open, and tries again a few minutes later, so a broken build cannot hold the TV in a loop either.

Verify a download

If you download the APK yourself, check it before installing. Put the APK and SHA256SUMS from the same release in one folder.

$ shasum -a 256 -c SHA256SUMS --ignore-missing
$ apksigner verify --print-certs shangos-v0.4.0-release.apk

$ sha256sum -c SHA256SUMS --ignore-missing
$ apksigner verify --print-certs shangos-v0.4.0-release.apk

PS> (Get-FileHash .\shangos-v0.4.0-release.apk -Algorithm SHA256).Hash
# compare with the line in SHA256SUMS
PS> apksigner verify --print-certs shangos-v0.4.0-release.apk

apksigner is part of Android’s build-tools. The certificate SHA-256 it prints must match the release notes on GitHub, and the one shown on the TV under Settings, Privacy, This build.

If something goes wrong