# HPOS — Linux-Smartphone auf Stock-Android, ohne Root

> Arbeitstitel. Der Projektname steht noch nicht fest.

Ein beliebiges gebrauchtes Android-Smartphone wird zum Linux-Telefon: Debian 13 mit
Plasma Mobile in Termux/proot, mit einem Backup- und Provisioning-System drumherum,
das die eigentliche Substanz des Projekts ausmacht.

**Kein Root. Kein entsperrter Bootloader. Kein Server nötig.**

## Was es ist

"Linux auf dem Handy" gibt es schon. Was es nicht gibt, ist der Rest:

- **Backup mit echten Snapshots** — Einzeldatei-Restore, Web-Manager im Browser,
  ZIP-Export aufs Telefon, Ziele über SFTP/SMB/FTP/WebDAV
- **Provisioning in einem Rutsch** — Telefon auspacken, eine APK, ~20 Minuten, fertiges System
- **Klonen aufs neue Telefon per WLAN** — Gerätewechsel als Normalfall, nicht als Notfall
- **Bridge zum Android darunter** — SMS, Telefonie, Kamera, Sensoren erscheinen im Linux
  über Standard-D-Bus-Schnittstellen, sodass unveränderte Plasma-Anwendungen sie nutzen

Die Android-Installation darunter ist nur noch Treiber-Layer und Prozess-Host.
Alle Nutzdaten leben im Linux und damit im Backup.

## Status

**Phase 0 — Machbarkeits-Spike.** Vier Annahmen tragen das Projekt und werden zuerst
bewiesen, bevor Infrastruktur entsteht:

| | Annahme | Wenn es scheitert |
|---|---|---|
| **S1** | Plasma Mobile läuft in proot (genestetes KWin) | XFCE-Profil wird Hauptweg |
| **S2** | Mikrofon-Eingang erreicht die Linux-Seite | Keine Videocalls, keine Sprachaufnahme |
| **S3** | Virtuelle PipeWire-Kamera ohne Kernel-Modul | Kamera nur in einer eigenen App |
| **S4** | Intent-Handoff Linux → Android-App | Keine Navigation aus dem Linux-Adressbuch |

Noch nichts davon ist bewiesen. Die Skripte in [`spike/`](spike/) führen die Beweise;
Ergebnisse landen in [`docs/spike-protokoll.md`](docs/spike-protokoll.md).

## Loslegen

Getestet wird auf einem **OnePlus 7 Pro (Snapdragon 855, Adreno 640) mit Stock OxygenOS 12**.

Voraussetzung ist nur, dass die Entwickleroptionen aktiv sind. **Ein USB-Kabel wird
nicht gebraucht** — ab Android 11 läuft die Ersteinrichtung über WLAN.

### Auf dem PC

```bash
./provision/adb-wireless.sh      # Verbindung per WLAN (oder Kabel anstecken)
./provision/install-termux.sh    # lädt Termux + 3 Zusatz-Apps, installiert sie,
                                 # erteilt die nötigen Berechtigungen
./provision/provision.sh         # Akku- und Hintergrundeinstellungen,
                                 # legt das Startskript aufs Telefon
```

`provision.sh` allein genügt auch — es ruft die anderen bei Bedarf selbst auf.

### Auf dem Telefon, in Termux

```bash
bash /sdcard/hpos-init.sh        # installiert git, klont das Repo nach ~/hpos
cd ~/hpos

bash spike/00-bootstrap-termux.sh

bash spike/01-s1-plasma-mobile.sh   # S1 zuerst — der wackligste Beweis
bash spike/02-s2-mikrofon.sh
bash spike/03-s3-pipewire-kamera.sh
bash spike/04-s4-intent-handoff.sh
```

### Aktualisieren

Per adb kommt bewusst **nur das Startskript** aufs Telefon, nicht das Repo selbst.
Dadurch liegt dort eine echte Arbeitskopie — spätere Änderungen brauchen keinen PC:

```bash
cd ~/hpos && git pull
```

Details, Stellschrauben und was bei Fehlschlägen zu tun ist:
[`spike/README.md`](spike/README.md).

### Warum Termux nicht aus dem Play Store

Termux und seine Plugins teilen sich eine Android-UID. Android verlangt für Apps mit
gemeinsamer UID **denselben Signaturschlüssel** — mischt man F-Droid und GitHub,
scheitert die Installation mit `INSTALL_FAILED_SHARED_USER_INCOMPATIBLE`, ohne dass
die Meldung den Grund nennt. `install-termux.sh` nimmt deshalb durchgängig GitHub und
räumt vorhandene Installationen aus fremder Quelle auf Nachfrage weg.

Nebeneffekt der Entscheidung: Termux:X11 gibt es dort in einer sharedUid-Variante, die
in Termux' Prozessgruppe läuft und dessen Akku-Ausnahmen erbt. Bei ROMs, die
Hintergrund-Apps aggressiv beenden, ist das der Unterschied zwischen „läuft über Nacht"
und „war morgens weg".

## Dokumentation

- [Architektur](docs/architektur.md) — wie die Teile zusammenhängen
- [Machbarkeit](docs/machbarkeit.md) — was ohne Root geht und was nicht, mit Belegen
- [Verworfene Entscheidungen](docs/verworfene-entscheidungen.md) — sieben Wege, die
  geprüft und begründet verworfen wurden. **Vor jedem "warum eigentlich nicht …" lesen.**
- [Spike-Protokoll](docs/spike-protokoll.md) — Messergebnisse von Phase 0

## Geräte

| Gerät | SoC / GPU | Android | Status |
|---|---|---|---|
| OnePlus 7 Pro (`guacamole`) | Snapdragon 855 / Adreno 640 | OxygenOS 12 | 🔬 im Test |

Läuft es bei dir? [Geräte-Meldung eröffnen](.github/ISSUE_TEMPLATE/geraet-melden.md).

## Lizenz

GPLv3 — siehe [LICENSE](LICENSE).

Termux wird **nicht mitverteilt**: `install-termux.sh` lädt die APKs zur Laufzeit von
den offiziellen GitHub-Releases. Eine Quellen-Angebotspflicht entsteht dadurch nicht.
Sollte die Installer-APK in Phase 2 Termux als Asset mitbringen, ändert sich das —
die einheitliche GPLv3 deckt es dann ab.

---

# HPOS — a Linux phone on stock Android, no root

Turns any second-hand Android phone into a Linux phone: Debian 13 with Plasma Mobile
inside Termux/proot, wrapped in the backup and provisioning system that is the actual
point of the project.

**No root. No unlocked bootloader. No server required.**

Currently in **Phase 0** — proving four load-bearing assumptions (S1–S4 above) before
any infrastructure gets built. See [`spike/`](spike/) and
[`docs/spike-protokoll.md`](docs/spike-protokoll.md).

## Quick start

No USB cable needed — Android 11+ pairs over WLAN.

```bash
# On the PC
./provision/adb-wireless.sh      # pair and connect over WLAN
./provision/install-termux.sh    # download and remote-install Termux + addons
./provision/provision.sh         # battery/background settings, push init script

# On the phone, in Termux
bash /sdcard/hpos-init.sh        # installs git, clones this repo to ~/hpos
cd ~/hpos && bash spike/00-bootstrap-termux.sh
```

Updating later needs no PC: `cd ~/hpos && git pull`.

Documentation is currently German-first; English will follow once Phase 0 concludes.
Device reports are welcome in either language — a well-documented failure is as
valuable as a success.