Browser one-shot installer
What this installer does, and what it refuses to do.
This page is the operator's reference for the browser installer preview. It is published both as part of the development site (dev.libreecho.org/install/) and on its own hostname (install.dev.libreecho.org); every path in the app is relative, so both serve the same files.
The install route
The browser installer implements the same no-short route as the host installer, with the browser as the USB host:
| Stage | What happens | What it checks |
|---|---|---|
| Release | The published release inventory is read. | The normal and TWRP checksum files, ZIP, manifest and required assets must each match SHA-256 digests reported by the release API. Image safety is delegated to the release publisher; the verified build must match the detected board. Hardware-acceptance and recovery-protocol checks remain required. |
| Bundle | Payload bytes are selected locally. | Each file is hashed in the browser and compared with the release digest before it is used. |
| Device query (read-only) | WebUSB permission prompt, then targeted fastboot getvar reads. | Bootloader-reported product/model, lock state, LK and preloader builds, secure/RPMB state, download limit and full serial are shown in the local panel. The serial is masked in the log. |
| Unlock | The per-LK-build payload is submitted to the brick target. | The payload is only eligible if the detected build has a declared entry; the name is reported and the outcome is explicit. |
| Recovery | ADB connects to TWRP. | The ADB serial must match the earlier fastboot serial, and expdb must contain an intact Kaeru header before staging or running the ZIP. When the page has no fastboot identity (a reload while already in TWRP), the serial instead comes from ro.serialno read back from the recovery device, together with its board, TWRP version and Kaeru header. |
| Stage | The verified files are pushed to /cache/libreecho-bundle. | Every pushed file is re-hashed with the device's own sha256sum. |
| Prepare / Install | The recovery installer zip is run over ADB, twice if a reboot is required. | The installer's own receipt at /cache/libreecho-install-receipt is read back after each run. |
| Verify | The device is rebooted. The page then re-attaches to the running image's ADB (18d1:d001), from permission it already holds or after Check my Echo, and runs one read-only shell probe. | The serial from /proc/cmdline must match the install's serial; /run/libreecho/startup-ready, the web service and the setup-complete marker are presence tests. The page then closes the USB session and hands over to setup: a browser cannot create the host port forward the setup page needs, so that step is the guide's terminal command. |
Why the payloads come from your own download
Measured from a GitHub Pages origin (the development site), a browser can read api.github.com and raw.githubusercontent.com, but it cannot read github.com/<owner>/<repo>/releases/download/…: the redirect response carries no Access-Control-Allow-Origin header, so the fetch fails before any bytes are readable. The network path itself works — the response simply cannot be read by a page.
Two honest consequences:
- Default: download the release assets with your browser from the release page, then select them (or the whole folder) in the installer. Include both
SHA256SUMSandTWRPINSTALL-SHA256SUMS, thelibreecho-install.zipandbundle.manifest. Both inventories are checked against the GitHub release API's asset digests before their listed files are accepted. - Release download mirror: release files are fetched in-page from
https://dl.libreecho.org, a read-only CORS pass-through to the GitHub release download URLs (GitHub's own download endpoint cannot be read by a web page). The mirror is untrusted transport: every file is still checked against the release'sSHA256SUMSand GitHub's asset digests, and anything that does not match stops the download.?mirror=https://…points at a different mirror;?mirror=(empty) turns it off so only operator-selected files are used. A separate operator-approved?amonetMirror=https://…enables the pinned Amonet ZIP fetch button. None of these options bypass the archive, payload, release, board, hardware-acceptance or recovery-protocol checks.
Browser requirements
- Desktop Chromium-family browser (Chrome, Edge, Brave, Opera). Firefox and Safari do not expose WebUSB.
- HTTPS (or
localhost): WebUSB requires a secure context. GitHub Pages is HTTPS. - Direct device connection: a data-capable cable, and no hub in between if the device is fussy about enumeration.
- After fastbrick, TWRP may enumerate under a different USB identity. Use Connect to your Echo in recovery (or Allow USB access to TWRP in step 3) from a fresh button click if the browser has not authorised that identity; the page checks the original fastboot serial and Kaeru header before any recovery write. Chrome's list is scoped to TWRP's identity
18d1:4ee2(Radar and Echo Dot) and LibreEcho's own18d1:d001, but not to a serial, because TWRP's USB serial does not always equal the fastboot serial.18d1:d001is never accepted as recovery: it is listed only so an Echo already running LibreEcho can be recognised as installed. - If an Echo in TWRP reports a different serial than fastboot did, the page does not use it by itself; it may be a different Echo. If it is the one you just unlocked, stop the wait and press My Echo is already in recovery. That works without reloading the page, keeps the verified download, and never sends the unlock again.
- An Echo that is already running LibreEcho (
18d1:d001, nogetprop) is recognised from LibreEcho's own markers (/etc/libreecho/targetand the serial on/proc/cmdline) and reported as installed, not as "TWRP is not running". Chosen from My Echo is already in recovery or from a fastboot query, the page hands it to the read-only post-install check, which shows how to open setup (adb forward tcp:18080 tcp:8080, thenhttp://127.0.0.1:18080/setup.html). If it answers during an install's recovery wait with the identified serial, the wait says so: before any install phase, Stop hands over to that same check; afterprepareasked for a reboot to recovery, the page tells you to enter recovery by hand (unplug, hold Volume Up (+) only, plug back in) and keeps waiting. - Resuming an install: before any install phase, the page reads the Echo's own install record in TWRP (
/cache/libreecho-direct/transaction.stateandreceipt, read-only) and checks that it belongs to the selected build (bundle manifest digest, target, release) and to this Echo (the helper's device digest, recomputed from TWRP). That record, not the browser, decides: finalized withresult=installedruns nothing and goes straight to restarting into LibreEcho and setup; not yet formatted continues atprepare(safe to repeat); formatted continues attransfer. An uncertain format (format_state=formatting), an interrupted finalize (phase=finalizing), a record for another build or device, or one the page cannot read stops with the exact state and the safe next step. The page's own per-phase attempt record in the browser is only passed when the Echo's record proves what the earlier attempt did, and the install transaction is never reset from the page. - "Unable to claim interface" means another program on the computer holds the Echo's USB connection, most often
adb(Android platform tools, Android Studio, scrcpy) or a second tab with this installer. Runadb kill-server, close the others and press the button again. If it still fails, reload the page and use My Echo is already in recovery. - Starting from a device already in recovery: if your Echo is already unlocked and sitting in TWRP — including after a page reload — a fastboot query cannot work, so use My Echo is already in recovery in step 3 (or the status-bar button) instead. It reads the device's identity from the recovery environment itself and accepts it only when all of these hold — the same checks the command-line installer makes before it trusts a recovery device: a non-empty
ro.serialno, an exact LibreEcho board name inro.product.device, a running TWRP (ro.twrp.version), and inexpdb(resolved from sysfsPARTNAME) an LK header that chains to a Kaeru header. If any check fails, nothing is identified and nothing is written. Find previously authorised recovery takes the same route when no device is identified yet, and a fastboot query that finds the Echo in TWRP carries on into it with the same USB device instead of asking for another click. The chooser is scoped to18d1:4ee2, which is TWRP on both the Echo 2nd Gen and the Echo Dot, and18d1:d001, which is LibreEcho's own ADB on an installed Echo, not TWRP. The identity is never trusted from the USB ids, and because there is no serial to narrow it with yet, every check is made from what the device itself reports. No unlock payload is ever sent from this entry: an intact Kaeru header is itself the evidence that the unlock already happened. All the usual release gates still apply, including that the selected build must match the device's board.
USB identities the installer expects
The device chooser is filtered with the identities an Echo presents in each mode. The page needs no filter entry for a mode it does not use, but a missing entry means an empty chooser, so the unfiltered Show all USB devices… button exists as the escape hatch.
| Mode | USB identity | How it presents |
|---|---|---|
| Fastboot (stock or unlocked) | 0bb4:0c01 (measured), 18d1:4ee0–18d1:4ee7, 18d1:d00d, 0e8d:201c, 0e8d:2001 | Vendor-specific interface with a bulk in/out pair; getvar product answers. 0bb4 is HTC's vendor id and is what this platform has been seen to present in fastboot. |
| ADB — installed LibreEcho image | 18d1:d001 (measured) | Interface at class 0xFF subclass 0x42 protocol 0x01; product string MT8163-ARM32-ADB. |
| ADB — TWRP recovery | 18d1:4ee0–18d1:4ee7, 18d1:d00d | Same ADB interface triple; TWRP answers without an authentication token. |
| Preloader USB download | 0e8d:2000 (measured) | CDC-ACM pair, device class 2, product string like Failed to load LK. This is a download-mode state awaiting a host tool, not fastboot, and it resets on a timer if nothing connects. |
| Boot ROM (BROM) | 0e8d:0003 | Reached with the eMMC short or a cleared preloader header. |
These devices report device class 0 with per-interface classes, so a WebUSB classCode filter never matches them: an identity has to be named, or the chooser left unfiltered.
What the installer will not do
- It never guesses an unlock payload. A locked device whose LK build has no pinned member is refused outright; the only exception is the operator tick box Allow untested LK build (step 4), which sends the archive's own default
fastbrick.imgafter the same size and SHA-256 checks, announces before the write that the combination is untested, is never pre-ticked, and is dropped as soon as the device or its build changes. Every single-submission guard still applies. After Query Device, it selects the exact LK-build member from a SHA-256-pinned Amonet ZIP. The ZIP may come from an explicitly configured CORS mirror or a local file selection; the extracted member is separately size/hash-checked before use. The site does not bundle or redistribute Amonet binaries. - It records a hashed device/payload unlock attempt in local browser storage before submission. A timeout or disconnect is unknown; a second tab or page reload cannot silently resubmit the same payload. Each recovery ZIP phase is similarly recorded before execution and cannot be replayed without manual state classification.
- The page never directly writes an ASCII
FASTBOOT_PLEASEmarker. The fastbrick unlock payload itself writes critical boot-chain regions (including Kaeru inexpdb, preloader, LK, TEE, recovery and RPMB). A recovery ZIP and boot image are separate execution inputs; no "never writes expdb" claim covers them. The release publisher is responsible for image safety and boot-chain compatibility. This page verifies publication integrity and board matching without a separate manual image-safety flag, and still checks the Kaeru header before and after recovery phases. - It never trusts a transfer result: pushed files are re-hashed on the device, and the install result comes from the installer's receipt.
- It never publishes a device identifier. The full serial is shown only in the local device panel for target confirmation; terminal output and saved logs mask it. A hashed identifier is stored locally to prevent an ambiguous unlock retry.
- It does not format or reshape partitions from the browser. That work exists in recovery (
sgdisk,mke2fs) and is done there, by the installer zip, on the device.
Status
This is a fail-closed preview. The read-only fastboot Query Device stage has been tested over WebUSB on an Echo Dot 2; unlock, recovery and installation have not been hardware-tested from a browser. Run requires a verified, target-matching, hardware-accepted published build with direct-userdata protocol v2 metadata. Image safety is the release publisher's responsibility, not an additional browser qualification flag. The Dot has experimentally run a Radar image on its shared MT8163 hardware, but that cross-board result does not qualify a one-shot Biscuit install. Rehearse performs local/read-only checks only and cannot submit an unlock payload or install ZIP.
Reporting
Use the installer's Save log button and attach the log with the exact release tag, the device mode you started from (stock fastboot or recovery), and the first message that did not match this page. Do not paste device serials, MAC addresses, Wi-Fi credentials or provider tokens.
← Back to the installer