# debian-on-amlogic puts a mainline Debian or Ubuntu on a cheap TV box without touching its bootloader

> This project publishes minimal Debian Trixie and Ubuntu images for Amlogic OTT TV boxes, built on a mainline LTS kernel and booted with the vendor u-boot rather than a chain loaded one. It is deliberately a server image, not a desktop or a media player, and the README is unusually honest about which boxes lose wifi or sound.

**devmfc/debian-on-amlogic** — Minimal Debian and Ubuntu images for Amlogic based Android TV-boxes with mainline Linux LTS kernel.

- Repository: https://github.com/devmfc/debian-on-amlogic
- Stars: 1,031 · Forks: 82
- Language: Unknown
- License: GPL-2.0
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/devmfc-debian-on-amlogic

## A vendor Android box with a mainline kernel behind it

The images are described as minimal Debian and Ubuntu Linux images for Amlogic based OTT TV boxes with a mainline Linux LTS kernel. The current pair is Debian Trixie, which is version 13, with Linux kernel 6.18.55, and Ubuntu Resolute Raccoon, which is 26.04 LTS, with the same kernel version.

The reason the author built them is stated plainly. These are the images he uses himself for various projects and small server tasks such as email, Pi-hole, Nextcloud, NAS and a webserver, and for those he wanted a mainline LTS kernel rather than an older and sometimes buggy or insecure vendor kernel. The second stated goal was a standard and clean Debian or Ubuntu distribution without unknown or untrusted APT repositories.

The author also states the motivation plainly in the negative. It is a hobby of tinkering with cheap Android TV boxes, published in case someone else wants to do the same, and he is explicit that he does not have the time to be anyone's Linux teacher and does not expect to provide support. That framing matters for anyone reading the compatibility lists, because the list of tested boxes is a personal compatibility record rather than a support commitment.

The repository itself is minimal, holding only a LICENSE file and this README, so the images are the artefact and the documentation is the source of truth for how they behave.

## The boot script uses the vendor bootloader and changes nothing

The distinguishing design decision is in the boot process. The README states three things in sequence. The boot script uses the vendor bootloader on the box, so there is no bootloader in the image. The boot script does not use a chain loaded bootloader. And the boot script will not install multiboot or modify the bootloader environment with its boot procedure.

The consequence is stated as well, and it cuts both ways. Since the boot environment is not touched, it is almost impossible to damage or brick the device while trying to boot with this image, but you also have to press the reset button every time you want to boot from this image. The device still boots into its stock Android otherwise, which is a genuinely different arrangement from the usual Android TV box Linux images that rewrite the bootloader to chain load a mainline one.

The escape hatch is documented. You can install multiboot by running ./aml-multiboot-setup.sh in the /root directory once booted into Linux, and the README is blunt that this script will change the bootloader environment, that there is a chance, described as very small but still, of bricking the box, and that if you lack the tools, images or knowledge to unbrick it you have been warned.

In other words, the safe default and the convenient default are opposites here, and the project lets you choose which one you want rather than choosing for you.

## One line in boot.config selects the device tree

The installation is a flash and a text edit. The steps are: burn the image to a USB flash disk, or an sdcard, though the README notes USB is more reliable, using an image burner such as Balena Etcher, Win32DiskImager or dd. Then open boot.config on the first FAT partition with an editor, uncomment the box= line for your box, and save the file.

That single line is the whole device selection mechanism, and the list of values it can take is the compatibility list in the README. Boxes with their own device tree are listed individually, with the SoC and the Ethernet speed in brackets, for example the A95X with S905, the A95X F2 with S905X2, the Beelink GT King with S922X, the H96 Max W2 with S905W2 and 100M ethernet, the H96 Max X3 with S905X3 and 1000M ethernet, the Vontar X4 with S905X4, and a long list of X96 and Tanix variants.

The parenthesised note is about device specific hardware: the list of boxes with a box specific DTB covers bluetooth, leds and the vfd display.

For everything else there are generic device trees, one per SoC family, with the Meson chip name in brackets.

```
- S905 (Meson GXBB)
- S905L-3 (Meson GXLX2, NO HDMI output!)
- S905W (Meson GXL)
- S905W2 (Meson S4)
- S905X (Meson GXL)
- S905X2 (Meson G12A), 100M and 1000M ethernet
- S905X3 (Meson SM1), 100M and 1000M ethernet
- S905X4 (Meson SC2), 100M and 1000M ethernet
- S905Y4 (Meson S4)
- S912 (Meson GXM), 1000M ethernet
- S922X (Meson G12B), 1000M ethernet
```

The S905L-3 entry carries its own warning in the list, that it has no HDMI output, which is the kind of detail you only find in a compatibility table written by someone who has tried the hardware.

## Two ways in, one of them over adb on a rooted Android

The start procedure assumes the reset button on the box. Put the disk in the box, hold the reset or update button, and power on. The README is candid that in most cases this button is hidden in the av port and needs a toothpick or cotton tip to press. Hold it for about seven seconds, longer does not hurt, and the box should boot to Debian or Ubuntu.

There is an alternative for boxes with rooted Android, described as a fallback in case of trouble with the reset or update button. It goes over adb, and the commands are short.

```bash
adb connect <box-ip>
```

Then inside the box shell, switch to root with su root and run reboot update, and the box reboots into the update slot. The consequence of this route is stated as the last step of the alternative: it will now boot to Debian or Ubuntu each time the disk is put in the box.

Either way, the login section says to connect by console or SSH, notes that at first boot SSH can take a little longer to become available because all encryption keys are regenerated, and gives the credentials as the user root with the password tvbox. The password is fixed in the image, so it is a detail to change on first boot before the device is on a network you care about.

## The exception list is the useful part of the compatibility table

The README separates hardware support into three tiers, and the middle and bottom tiers are where the value is.

In most cases HDMI, HDMI sound, USB 2 and 3, eMMC, SDCARD, Ethernet at both 100M and Gigabit, wifi, bluetooth and the VFD led display work. Then there are exceptions, listed by model: on the A95X F2 the MT7668 bluetooth will not work although wifi does, and on the X96 Max Plus 2101W, the X96 Max Plus Ultra and the X96 Mini the wifi does not work because of the aml_w1 driver. Two SoC families lose audio entirely, since all S905X4 boxes have no sound and all S905W2 boxes have no sound, and most S905W2 boxes have no working wifi.

Below that are two untested categories. CEC and IR are not tested but are expected to work. The S/PDiff port and the av port are not tested and are not expected to work, which is worth noting because the av port is where the reset button usually hides.

The pattern across the exceptions is a driver problem with a specific wifi chip, and it is the direct consequence of the mainline kernel choice. The README states the kernel is based on the mainline kernel source from kernel.org, with only the SC2 and S4 SoCs needing some extra patches, and that some work for S4 and SC2 is already in the author's own Linux repository, along with wifi MT7688 modifications for mainline.

## A kernel update is a .deb installed with dpkg

Updating the kernel on an existing installation does not require reflashing. The README describes copying the linux-image-xyz.deb file to a directory on the box, for example with scp, samba or a USB flash disk, and then running dpkg -i on it in that directory.

```bash
dpkg -i linux-image-xyz.deb
```

The instruction that follows is the important one: try the new kernel on a removable USB disk or sd-card first, so you will not brick the box when the kernel does not work. That is a direct consequence of the boot design, since the image boots through the vendor u-boot and the fallback path to a working system is the reset button rather than a bootloader menu.

The version scheme for the images follows the kernel rather than the distribution. The tags are v6.18.55, released on 2026-10-04, v6.18.49 from 2026-09-02 and v6.18.40 from 2026-07-27, so the tag tells you the kernel version, and the distribution is chosen by which image file you download rather than by the tag. The last push was on 2026-10-04, the same day as the newest tag, and the project is not archived, so the images are being rebuilt as the LTS kernel moves.

## What these images are not, and where the alternatives are

The README has an explicit section on what the images are not, and it is more useful than most compatibility documentation.

They are not suitable for media players like Kodi, and the advice given is to use Coreelec or Libreelec for that. The author does test a Linux desktop installation occasionally and there is a simple install script, but the judgement is that these TV boxes, without the hardware acceleration that vendor kernels provide, are far too slow for desktop use.

The images are also not a distribution. The wording is that this is not an attempt to become some kind of Linux distribution, it is just Debian or Ubuntu, so there is no support beyond the existing support sources for Debian and Ubuntu. And they are not Armbian, and are not based on Armbian.

The named alternatives for better hardware support are the Coreelec images and the Khadas Fenix images, which is the same advice given for media playback. That is a sensible division of labour: a box that is going to be a media centre wants a vendor kernel with hardware video acceleration, and a box that is going to be a small server wants a mainline kernel with a predictable security story and clean package repositories.

The licence is GPL 2.0, with the file at the repository root, which is the usual expectation for a distribution image that ships kernel and package content.

## Conclusion

Use these images if you want to repurpose a spare Amlogic TV box as a small always on server, for tasks like Nextcloud, a NAS or a Pi-hole substitute, and you are comfortable flashing USB media and editing a config file by hand. Do not use them as a media player or a desktop, and do not expect a box with a 100M Ethernet port or an S905X4 to behave like a better equipped one. Verify first which kernel release the image you download corresponds to, since the tag names track the kernel version rather than a Debian release, and read the exception list for your exact model before you flash anything.

## FAQ

### How do I install Debian on an Amlogic TV box?

Burn the image to a USB flash disk with Balena Etcher, Win32DiskImager or dd, then open boot.config on the first FAT partition, uncomment the box= line for your model and save it. Put the disk in the box, hold the reset or update button while powering on for about seven seconds, and the box boots to Debian or Ubuntu.

### Will this image brick my TV box?

The boot script uses the vendor bootloader and does not modify the bootloader environment, so the README describes it as almost impossible to damage the device while trying to boot with this image. The tradeoff is that you must press the reset button every time. The optional ./aml-multiboot-setup.sh script does change the bootloader environment, and the README warns that there is a small chance it can brick the box.

### How do I log in after the first boot?

The README says to log in via console or SSH, with the user root and the password tvbox. At first boot SSH can take a little longer to become available, because all encryption keys are regenerated.

### Does the box keep booting into Android, and can I avoid the reset button?

The boot script does not modify the bootloader environment, so the box still boots its stock Android by default, and you have to hold the reset button each time you want to boot from the image. For boxes with rooted Android the README offers an alternative over adb, using adb connect, then su root and reboot update, after which the box boots to Debian or Ubuntu whenever the disk is present.

### Can I update the kernel without reflashing the image?

Yes. Copy the linux-image-xyz.deb file onto the box, for example with scp, samba or a USB flash disk, and run dpkg -i on it. The README advises trying the new kernel on a removable USB disk or sd-card first so a non working kernel does not brick the box.

## Sources

- [devmfc/debian-on-amlogic on GitHub](https://github.com/devmfc/debian-on-amlogic)
- [Issues](https://github.com/devmfc/debian-on-amlogic/issues)
- [License: GPL-2.0](https://github.com/devmfc/debian-on-amlogic/blob/main/LICENSE)
- [README](https://github.com/devmfc/debian-on-amlogic/blob/main/README.md)
- [Releases](https://github.com/devmfc/debian-on-amlogic/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/devmfc-debian-on-amlogic