los-bootstrap 0.9.0

CLI-first post-install assistant for LineageOS and degoogled Android ROMs.

   ██╗      ██████╗ ███████╗  ╷  ╔╗ ╔═╗╔═╗╔╦╗╔═╗╔╦╗╦═╗╔═╗╔═╗
   ██║     ██╔═══██╗██╔════╝  │  ╠╩╗║ ║║ ║ ║ ╚═╗ ║ ╠╦╝╠═╣╠═╝
   ██║     ██║   ██║███████╗  │  ╚═╝╚═╝╚═╝ ╩ ╚═╝ ╩ ╩╚═╩ ╩╩
   ██║     ██║   ██║╚════██║  │
   ███████╗╚██████╔╝███████║  │
   ╚══════╝ ╚═════╝ ╚══════╝  ╵

A CLI-first toolkit for LineageOS and other AOSP-derived, degoogled Android ROMs — covering the full journey from locked bootloader to a hardened, privacy-audited daily driver.

Status: Phase 8 — ROM flashing assistant. los-bootstrap flash guides you through bootloader unlock and ROM sideload with manufacturer-specific steps for Pixel, OnePlus, Fairphone, Motorola, Samsung (Heimdall), and Xiaomi (Mi Unlock Tool). All prior subcommands are unchanged. Mutating commands only run with explicit --confirm. See roadmap.md for what comes next.

Why

Getting onto a degoogled ROM used to mean piecing together a dozen forum posts: unlock the bootloader here, find the right recovery there, figure out why location is broken, hunt for the right GCam port, and remember which Google package crept back in. los-bootstrap covers the whole process end-to-end from a single CLI:

• Full lifecycle. Bootloader unlock → ROM flash → privacy audit → hardening → app bootstrap → location diagnostics → camera tuning.
• Honest about tradeoffs. Every recommendation surfaces its downside. "Unlock your bootloader" also tells you about the verified-boot warning and data wipe. "Enable location" also tells you who can see it.
• Manufacturer-aware. Pixel/OnePlus (standard fastboot), Motorola (unlock key portal), Samsung (Heimdall + Odin fallback), Xiaomi (Mi Unlock Tool + mandatory waiting period) — each gets a real guide, not a generic "check your XDA thread."
• CLI over GUI. Every feature is reachable from the terminal. No web UI, no app to install on the device first.
• Pluggable. Device-specific knowledge lives in YAML, not if-trees.

Install

One-liner (recommended)

Linux / macOS:

curl -fsSL https://raw.githubusercontent.com/richardkfm/los-bootstrap/main/scripts/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/richardkfm/los-bootstrap/main/scripts/install.ps1 | iex

The install script detects your OS, installs pipx and adb via your system package manager (apt / dnf / pacman / brew / winget), then runs pipx install "los-bootstrap[wizard]". It prints every command before running it, supports --dry-run (preview only), and exits cleanly if your package manager isn't recognised.

Audit-first variant (recommended on machines you don't fully control):

curl -fsSL https://raw.githubusercontent.com/richardkfm/los-bootstrap/main/scripts/install.sh -o install.sh
sha256sum -c install.sh.sha256   # checksum is published on the GitHub Release
sh install.sh

Caveats — surfaced honestly:

• adb is required and is installed via your OS package manager, not bundled. On unusual distros or locked-down corporate machines the script will exit with a "install platform-tools manually" message.
• fastboot and heimdall are only needed for flash run and Samsung devices. The install script does not install them by default; the flash subcommand prints what to install when needed.
• Piping a script into sh is a trust decision. The script is in this repo (auditable diff), short enough to read in one sitting, and ships with a SHA-256 checksum on every release.

If you already have Python and adb

pipx install "los-bootstrap[wizard]"

The [wizard] extra adds questionary for arrow-key menus. Without it the wizard falls back to numbered input() prompts.

From source (contributors)

Requires Python 3.10+ and the adb binary on $PATH.

git clone https://github.com/richardkfm/los-bootstrap
cd los-bootstrap
python -m venv venv
source venv/bin/activate
pip install -e ".[wizard,dev]"

source venv/bin/activate.fish for fish shell. On Windows, pip installs the los-bootstrap script into a Scripts folder that is often not on PATH — pipx (used by the install scripts above) handles this for you; in a manual venv install you may need to add Scripts to PATH yourself.

Arch Linux / PEP 668 error? Modern Python distributions protect system Python with PEP 668. The virtual environment above handles this; the pipx-based one-liner above also handles it without a venv.

Quick start

Flashing a ROM (Phase 8)

# 1. Check what state your device is in and identify the manufacturer
los-bootstrap flash status

# 2. Get the full bootloader unlock guide for your device (with live pre-checks)
los-bootstrap flash prepare

# 3. Verify your ROM zip targets the right device before flashing
los-bootstrap flash verify ~/Downloads/lineage-21-*.zip

# 4. Preview the flash sequence without running anything
los-bootstrap flash run ~/Downloads/lineage-21-*.zip --recovery ~/Downloads/recovery.img --dry-run

# 5. Execute the flash (destructive steps require --confirm)
los-bootstrap flash run ~/Downloads/lineage-21-*.zip --recovery ~/Downloads/recovery.img --confirm

After the ROM is installed

Plug in your phone, enable USB debugging, accept the RSA prompt, then:

los-bootstrap                    # launch the interactive guided wizard

Or use individual subcommands directly:

los-bootstrap devices            # list connected devices
los-bootstrap info               # device, ROM, build, security patch
los-bootstrap audit              # privacy/degoogle audit
los-bootstrap report             # full report (info + audit)
los-bootstrap report --json      # machine-readable
los-bootstrap recommend          # non-binding bootstrap suggestions

los-bootstrap profiles list                       # list bundled profiles
los-bootstrap plan    --profile privacy-default   # dry-run a profile
los-bootstrap apply   --profile privacy-default --confirm

los-bootstrap harden                              # lockdown report with why + tradeoff
los-bootstrap harden --interactive                # walk through findings, show fix commands
los-bootstrap harden --interactive --confirm      # walk through and apply fixes via adb
los-bootstrap harden --root                       # add SELinux check (needs su access)

los-bootstrap location doctor                     # diagnose the location stack on device
los-bootstrap location compat                     # app location compatibility matrix

los-bootstrap camera list-profiles                # list known GCam port profiles
los-bootstrap camera show panther                 # full port details + XML config path

If you have more than one device connected, pass --serial <id>. The camera, location compat, and flash prepare commands work without a device.

What it currently does

ROM flashing assistant (Phase 8)

los-bootstrap flash status    # detect device state + manufacturer
los-bootstrap flash prepare   # manufacturer-aware unlock guide
los-bootstrap flash verify    # validate ROM zip
los-bootstrap flash run       # execute the flash sequence

flash status detects whether your device is in normal ADB mode, fastboot/bootloader mode, or recovery, and identifies the manufacturer from ro.product.manufacturer.

flash prepare shows the full bootloader unlock walkthrough for your specific device, plus live pre-checks (Developer Options enabled? OEM unlocking enabled?) when the device is accessible via ADB:

Manufacturer	Approach
Google Pixel, OnePlus, Fairphone	Standard fastboot flashing unlock
Motorola	Unlock key from motorola.com, then fastboot oem unlock
Samsung	Heimdall (open-source, cross-platform); Odin fallback guide
Xiaomi / Redmi / POCO	Mi Unlock Tool walkthrough (Windows, 7–30 day wait)
Unknown / generic	XDA-oriented generic fastboot guide

flash verify extracts pre-device from the ROM's OTA metadata and cross-checks it against the connected device codename — a wrong-device catch before anything destructive runs.

flash run executes the sequence. It detects A/B vs A-only partition layout (fastboot getvar slot-count) and adjusts accordingly. Every destructive step is skipped without --confirm. --dry-run prints the full command sequence without running any of it.

Audit (Phase 1)

• Detects connected devices via adb devices.
• Reads ROM identity from getprop (ro.build.*, ro.product.*, ro.lineage.* when present).
• Runs a privacy audit:
  • Google Mobile Services (com.google.android.gms) presence
  • Google Services Framework (com.google.android.gsf) presence
  • Common Google client packages (Maps, Play Store, GBoard, etc.)
  • ADB-over-network (service.adb.tcp.port) state
  • Private DNS (DoT) configuration
  • Screen lock configuration
• Renders findings as a human-readable report (or JSON).
• Suggests bootstrap actions — without applying them.

Bootstrap profiles (Phase 2)

Builds and applies profiles: a YAML-described list of apps to install and settings put toggles. Bundled profiles:

• minimal — F-Droid + Private DNS
• privacy-default — adds maps, contacts, a browser, and DoT
• messaging-light — Signal, Element, Telegram X
• max-tools — broadest non-Google bundle: store, browser, maps, messaging, contacts/calendar, mail, media, productivity, password manager, RSS/podcasts, and ReVanced Manager for ad-free YouTube
• camera — sideloads LMC 8.4 from a manually staged APK (see below)

APKs are downloaded automatically when apply runs:

Source in profile	How it's fetched
source: sideload + url: https://…	Downloaded directly
source: sideload + url: github://owner/repo	Latest .apk release asset from GitHub
source: fdroid	Resolved via F-Droid API → downloaded from f-droid.org/repo/
source: aurora	Manual — Aurora Store handles Play Store apps

Pass --no-fetch to disable downloads and revert to manual staging.

los-bootstrap plan  --profile privacy-default               # dry-run
los-bootstrap apply --profile privacy-default --confirm     # execute
los-bootstrap apply --profile privacy-default --apk-dir ~/los-apks --confirm

Hardening assistant (Phase 3)

Runs lockdown checks and guides you through each one:

Check	What it detects
dev.options	Developer options enabled
dev.adb	USB debugging (ADB) enabled
sec.screen_lock	Screen lock disabled
sec.encryption	Unencrypted storage
sec.unknown_sources	Global unknown-sources install flag
sec.verified_boot	Bootloader unlocked / verification failed
sec.lockdown_menu	Lockdown option absent from power menu
sec.selinux	SELinux permissive (--root only)

Every finding explains why it matters and what you give up by hardening it. --interactive walks through each WARN/FAIL one at a time and offers to apply the fix; --confirm is required to execute.

Location stack (Phase 4)

los-bootstrap location doctor   # diagnose the device's location stack
los-bootstrap location compat   # static app compatibility matrix

location doctor checks: location master switch, real GMS conflict with microG, microG GmsCore install, signature-spoofing grant, and which UnifiedNlp network-location backends are installed. Every finding has a why and a tradeoff.

location compat shows a static matrix of 14 real-world apps (OsmAnd, Telegram, Signal, WhatsApp, Firefox, Chromium, Uber, and more) rated as yes / gps-only / partial / no on a degoogled ROM. No device connection required.

Camera / GCam port profiles (Phase 5)

los-bootstrap camera list-profiles      # table of known device profiles
los-bootstrap camera show <codename>    # full details + XML config path

No device connection required. Per-device profiles include:

• Which GCam port is recommended (LMC 8.4, BSG 9.3, etc.)
• Verified/unverified tag — only marked verified from real usage reports
• Source guidance: where to download the correct build for your SoC
• XML config path (/sdcard/GCam/Config/) and the exact adb push command to apply it

Currently profiled devices:

Codename	Device	Port
panther	Google Pixel 7	LMC 8.4 R17
oriole	Google Pixel 6	LMC 8.4 R17
sunny	Xiaomi Redmi Note 10	BSG 9.3.020 (+ LMC 8.4)
lemonade	OnePlus 9	BSG 9.3.020
FP4	Fairphone 4	LMC 8.4 R17
renoir	Xiaomi Mi 11 Lite 5G	LMC 8.4 R17

Device not listed? GCam ports are matched by SoC, not device name. Run adb shell getprop ro.board.platform to find your chip, then look for a matching build on celsoazevedo.com or your device's XDA thread. camera list-profiles shows the full guidance.

Sideloading LMC 8.4

GCam APKs are proprietary — they are never auto-fetched by this tool. To install via the camera bootstrap profile:

# 1. Download LMC 8.4 for your SoC from celsoazevedo.com
# 2. Rename it to lmc84.apk and place it in ~/los-apks/
los-bootstrap apply --profile camera --apk-dir ~/los-apks --confirm

# 3. Push the XML config (get the exact command from camera show)
los-bootstrap camera show <your-codename>

Interactive wizard and enriched output (Phase 6)

Run los-bootstrap with no arguments to launch the guided wizard:

• Detects your connected device and enters offline mode if none is found
• Main menu: Audit → Harden → Bootstrap → Location → Camera
• Audit screen — runs all checks and shows findings grouped into issues to address and passing checks, with word-wrapped prose
• Drill-down — select any finding for a full "what's happening / why it matters / how to fix it / tradeoff" explanation
• Harden screen — choose read-only report or interactive walk-through; per-finding confirmation before applying any fix
• Bootstrap screen — profile picker → plan review → apply with confirmation
• Location / Camera screens — same diagnostics as the subcommands
• Offline mode — no ADB device? Camera and Location compat still work

All finding renderers are also improved in standalone (non-wizard) mode: findings are now grouped by severity, long prose is wrapped at 72 chars, and → Fix: / ⚠ Tradeoff: labels replace the old flat field list.

  ✗  Location disabled
     Location must be on for GPS, network, and passive providers to
     function. With it off, every app requesting a location fix receives
     nothing, regardless of backends or microG installed.

     → Fix: Settings › Location › Use location — toggle on.
     ⚠  Tradeoff: Enabling location allows apps with location permission
        to request your position. Only individually granted apps receive
        results.

Optional dependency: install questionary for arrow-key menus:

pip install "los-bootstrap[wizard]"

Without it the wizard falls back to numbered input() prompts and works everywhere.

What it does NOT do

• It does not bypass bootloader verification or carrier locks — it calls official unlock APIs only.
• It does not fetch ROMs from the network — you supply the zip file.
• It does not automate Samsung Odin (closed-source, Windows-only) or Xiaomi's Mi Unlock Tool (proprietary, server-enforced). It guides you through those manually.
• It does not auto-distribute GCam APKs or other proprietary binaries.
• Root is opt-in (harden --root) and only used to read SELinux state.
• It does not verify APK signatures — verify downloads out-of-band for security-critical installs (F-Droid, ReVanced Manager).

These and future plans are tracked in roadmap.md.

Project layout

See CLAUDE.md for the architecture, coding workflow, versioning policy, and roadmap discipline rules.

License

GPL-3.0. See LICENSE.