waazaafr/apk-installer repository overview

⁠APK Installer

Deploy APKs to your Android devices over the network, from a web interface.

Push an APK to your Android TVs, set-top boxes and phones with a single link, or let APK Installer install every new GitHub release automatically on the devices you choose. Built for sideloaded apps that are not on the Play Store, on devices you don't want to plug in.

⁠Features

• 📺 Android TV / Google TV / set-top boxes (network ADB) and Android 11+ smartphones (wireless debugging)
• 🔍 Devices discovered automatically on the network (mDNS)
• 🚀 Manual install from a link to an .apk, or to an archive (.zip, .tar.gz…) containing one
• 🔄 Automatic install of the latest GitHub release on each target device, pre-releases excluded by default
• 🧩 ABI check before every install: an APK built for the wrong architecture is never pushed
• 🎯 One asset per device when a release ships one build per ABI (armeabi-v7a, arm64-v8a…)
• ♻️ Handles signature conflicts (e.g. a Play Store build already installed): uninstall, then reinstall
• 🔐 Login-protected web interface
• 📜 Live activity log
• 🔔 Notifications by Discord, Gotify⁠ or email (SMTP)
• 🖥️ Multi-arch image: linux/amd64 and linux/arm64

⁠Quick start

⁠Docker Compose

services:
  apk-installer:
    image: waazaafr/apk-installer:latest
    container_name: apk-installer
    restart: unless-stopped
    network_mode: host
    volumes:
      - ./data:/data
    environment:
      TZ: "Europe/Paris"

⁠Docker run

docker run -d \
  --name apk-installer \
  --restart unless-stopped \
  --network host \
  -v ./data:/data \
  -e TZ=Europe/Paris \
  waazaafr/apk-installer:latest

Then open http://:8934 and create the administrator account.

⁠Authentication

On first launch, the web interface asks you to create the administrator account (password of 8 characters or more). It is stored hashed (PBKDF2) in /data/auth.json; sessions last 30 days.

After 5 failed logins, the address is blocked for 5 minutes.

⁠Adding a device

⁠Android TV / set-top box

1. On the device, enable Developer options, then Network debugging (or ADB debugging).
2. In the web interface, add a TV / boîtier Android device with its IP address (port 5555 by default), or pick it from the discovered devices. The app connects to it right away.
3. The "Allow debugging?" prompt appears on the TV screen: accept it (tick Always allow).
4. Click Vérifier la connexion on the device card: it switches to En ligne and its ABI is shown.

⁠Android 11+ smartphone

Wireless debugging changes its port at every reconnection, and requires a one-time pairing:

1. On the phone, enable Developer options → Wireless debugging.
2. In the web interface, add a Smartphone device with its IP address.
3. On the phone, open Pair device with pairing code. On the device card, click Découvrir le port d'appairage (or type the port shown on the phone), enter the 6-digit code, then click Appairer.
4. Once paired, the connection port is found again by mDNS before each install: nothing to update by hand.

⁠Installing an app

⁠Manual install

In Installation manuelle, paste a direct link to:

• an .apk file;
• or an archive (.zip, .tar.gz, .tgz, .tar, .tar.bz2, .tar.xz) containing an .apk.

Select the target devices, then click Installer. Each device is connected right before the install; follow the result in the activity log.

⁠Automatic install from GitHub releases

In Suivi GitHub, create a watch:

When a release ships one build per architecture, list them all and each device gets the right one:

*armeabi-v7a.apk, *arm64-v8a.apk

How a watch behaves:

• The latest release is installed on every target device that doesn't have it yet: right after the watch is created, at each new release, and when a device is added to the watch later.
• Devices that were offline are retried every 15 minutes, until the release is installed. Nothing is downloaded for a device that is not reachable.
• A device for which the release has no compatible APK is skipped until the next release, instead of failing again every 15 minutes.
• Vérifier maintenant checks for a new release immediately.

Releases are detected through the public https://github.com/<owner>/<repo>/releases.atom feed, then read through the GitHub API (60 requests per hour without a token).

⁠Notifications

In Notifications, add one or more channels and choose the events to receive:

⁠Configuration

⁠Environment variables

⁠Volume

The image contains no configuration: it always starts empty, so it can be shared as is. Downloaded files are deleted once installed.

⁠Port

⁠Development

Requires the adb binary on your machine.

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
APK_INSTALLER_DATA_DIR=./data uvicorn app.main:app --reload --port 8934

⁠Changelog

⁠1.0.0 — 2026-10-22

• Login-protected web interface: account created on first launch, or set with AUTH_USERNAME / AUTH_PASSWORD; AUTH_DISABLED for reverse-proxy setups.
• Multi-arch image (linux/amd64, linux/arm64); fixed the build on Debian 13 (adb package).
• Archives are extracted safely: files trying to escape the extraction folder are refused.
• Downloaded files are deleted once installed, and leftovers are cleaned at startup.
• GitHub watches skip pre-releases (new Inclure les pré-releases option), and handle tags containing / or special characters.
• A device with no compatible APK in a release is no longer retried (and notified) every 15 minutes.
• Nothing is downloaded for a device that is not reachable.
• Two installs can no longer run at the same time on the same device.
• New Vérifier la connexion button to refresh a device's status, e.g. after accepting the debugging prompt.

⁠Links

• 💬 Discord: discord.gg/p9xkjEw8ts⁠
• ☕ Buy me a coffee: buymeacoffee.com/waazaa⁠
• ☕ Ko-fi: ko-fi.com/waazaa⁠
• UnRAID license: unraid.net⁠