Mi Box setup

This guide is written for the Xiaomi Mi Box (tested on a Mi Box 4K running Android 12). Do it yourself with the commands, or hand it to an AI agent. Total time: about 15 minutes.

By commands · With an agent · Undo everything · Troubleshooting

What you need

A Mi Box on the same Wi-Fi or Ethernet network as your computer.
A computer with Android platform-tools (adb) installed.
Lucerra-Launcher-v0.1.0.apk from the GitHub releases.
For the debloat script on Windows: PowerShell. On macOS or Linux use the manual commands in step 5.

By commands

Turn on developer options
On the Mi Box: Settings (gear), Device Preferences, About. Press OK on Build seven times until it says you are a developer. Go back to Device Preferences, open Developer options and turn on USB debugging. If you see a Network debugging toggle, turn that on too.
Find the IP address of the box
Settings, Network and Internet, pick your network. The IP address is shown there. Note it as <tv-ip>. Reserve that address for the box in your router so it does not change.
Connect adb
```
adb connect <tv-ip>:5555
adb devices
```
Accept the Allow USB debugging? prompt on the TV (tick "Always allow"). adb devices should list <tv-ip>:5555 as device.

Install Lucerra

adb -s <tv-ip>:5555 install -r Lucerra-Launcher-v0.1.0.apk

It should print Success.

Make Lucerra the default Home

The stock Mi Box home keeps winning the Home key, so disable it. This is reversible. On Windows, from a clone of the repo:

powershell -File tools/debloat.ps1 -Device <tv-ip>:5555

On macOS or Linux, run the same steps by hand:

for p in com.google.android.tvlauncher com.google.android.apps.tv.launcherx com.google.android.tvrecommendations com.miui.tv.analytics com.xiaomi.statistic com.mitv.tvhome.michannel com.mitv.tvhome.mitvplus com.google.android.play.games; do
  adb -s <tv-ip>:5555 shell pm disable-user --user 0 $p
done
adb -s <tv-ip>:5555 shell cmd package set-home-activity dev.raj.lucerra/.MainActivity

This disables the stock home, recommendations, Xiaomi analytics, the MiTV channel and Plus apps, and Play Games. Nothing is uninstalled.

Turn on the remote apps button

adb -s <tv-ip>:5555 shell settings put secure enabled_accessibility_services dev.raj.lucerra/dev.raj.lucerra.KeyService
adb -s <tv-ip>:5555 shell settings put secure accessibility_enabled 1

This lets the remote apps button open All Apps.

Turn on Now Playing

adb -s <tv-ip>:5555 shell cmd notification allow_listener dev.raj.lucerra/dev.raj.lucerra.NowPlayingListener

The glass widget then shows Spotify or any media session.

Check it worked
```
adb -s <tv-ip>:5555 shell cmd package resolve-activity -a android.intent.action.MAIN -c android.intent.category.HOME
```
The output should name dev.raj.lucerra. Then press Home on the remote: you should see five favourites over a wallpaper. Press Up for All Apps, and the apps button should do the same.

With an agent

Use any coding agent that can run shell commands, such as Claude Code. Install platform-tools and download the APK first, then turn on developer options on the box (step 1 above) because that part needs the remote. Paste this prompt:

Set up Lucerra Launcher on my Xiaomi Mi Box with adb. The APK is at <path-to>/Lucerra-Launcher-v0.1.0.apk and the box is at <tv-ip>:5555.

Rules:
- Use only adb, and always pass -s <tv-ip>:5555.
- Before changing anything, run adb connect and adb devices, and tell me if the device is not listed as "device".
- Install the APK with adb install -r.
- Ask me before disabling any package. Disable only these, with pm disable-user --user 0: com.google.android.tvlauncher, com.google.android.apps.tv.launcherx, com.google.android.tvrecommendations, com.miui.tv.analytics, com.xiaomi.statistic, com.mitv.tvhome.michannel, com.mitv.tvhome.mitvplus, com.google.android.play.games. Touch no other package.
- Then run: adb shell cmd package set-home-activity dev.raj.lucerra/.MainActivity
- Enable the apps button: adb shell settings put secure enabled_accessibility_services dev.raj.lucerra/dev.raj.lucerra.KeyService, then adb shell settings put secure accessibility_enabled 1
- Enable Now Playing: adb shell cmd notification allow_listener dev.raj.lucerra/dev.raj.lucerra.NowPlayingListener
- Verify with adb shell cmd package resolve-activity -a android.intent.action.MAIN -c android.intent.category.HOME and show me the output.
- Print the exact undo commands at the end. Do not run them.

Review each command the agent proposes. The prompt limits it to the packages above, and it should ask before disabling them.

Undo everything

powershell -File tools/restore.ps1 -Device <tv-ip>:5555

Or by hand, on any system:

for p in com.google.android.tvlauncher com.google.android.apps.tv.launcherx com.google.android.tvrecommendations com.miui.tv.analytics com.xiaomi.statistic com.mitv.tvhome.michannel com.mitv.tvhome.mitvplus com.google.android.play.games; do
  adb -s <tv-ip>:5555 shell pm enable $p
done
adb -s <tv-ip>:5555 shell settings put secure enabled_accessibility_services ""
adb -s <tv-ip>:5555 uninstall dev.raj.lucerra

Press Home and the stock Mi Box home is back.

Troubleshooting

Connection refused or timed out: check USB debugging is on, the IP is right and both devices share one network. Restart the adb server with adb kill-server, then connect again.
Device shows "unauthorized": accept the prompt on the TV. If it never appears, revoke USB debugging authorizations in Developer options and reconnect.
Device shows "offline": run adb disconnect and adb connect again, or reboot the box.
Home still opens the stock launcher: re-run the set-home-activity command from step 5 and confirm the disabled packages with adb shell pm list packages -d.
Apps button does nothing: run the two commands in step 6 again, then reboot the box.
Now Playing stays empty: start playback in the media app, then re-run step 7.

After a factory reset or a system update, repeat steps 5 to 7. Disabled packages and permissions can be reset.