A webapp to sideload apps (.rpk) and watchfaces (.bin) onto Mi Band 8 / 9 / 10 straight from the browser on macOS, Windows and Linux. No software to install, no Android phone needed.
β This tool can brick your device. Use it at your own risk.
Independent project, not affiliated with Xiaomi. The protocol is ported from Gadgetbridge (AGPL-3.0).
π Use it now: https://miband.trinh.uk Β· User guide Β· Developer guide
As of 10/2026, every existing way to sideload requires installing software:
| Tool | Platform | Notes |
|---|---|---|
| Notify for Xiaomi | Android | Paid app, has a tab for installing third-party apps |
| Gadgetbridge | Android | Open source, has RpkService |
| AstroBox-NG | Win / Linux / Android / iOS (native app) | Rust core, the Tauri app is closed source, no public web version yet |
MiBand Hack fills that gap: open a web page and install.
| Device | Connection | Browser API | Status |
|---|---|---|---|
| Mi Band 9, 10, 9 Pro, 10 Pro | Bluetooth Classic (SPP) | Web Serial (Chrome/Edge β₯ 117, desktop) | Implemented, not yet tested on a real device |
| Mi Band 9 (on a Mac) | BLE V2 (fe95 / 005e, 005f) |
Web Bluetooth | Connect, auth (with the Device ID), device info, app and watchface lists tested (fw 2.3.98); app install not yet confirmed |
| Mi Band 9 Active | BLE V2 (fe95 / 005e, 005f) |
Web Bluetooth | Implemented, not yet tested on a real device |
| Mi Band 8 | BLE V1 (fe95 / 0051β0055) |
Web Bluetooth | Connect, auth, device info, watchface list and watchface install tested (fw 2.3.14, ~2 KB/s); takes no apps (.rpk) |
- Formats:
.rpk(Vela quick app), watchface v2 (header5A A5). Watchface v3 and firmware are deliberately not supported (firmware can easily brick the band). - Browser: desktop Chrome or Edge. Safari/Firefox have no Web Serial/Web Bluetooth.
- Linux: you may need to enable
chrome://flags/#enable-experimental-web-platform-features.
- Get the auth key: press "Get it automatically with your Xiaomi account", then scan the QR code with a phone signed in to Xiaomi. If no key comes out, use Other ways on the page (iPhone/iPad: the Mi Fitness folder; Android: the Mi Fitness log), see docs/GUIDE.md.
- Turn off Bluetooth on your phone so the band is free to connect.
- Mi Band 9/10: pair the band in the OS Bluetooth settings first.
- Open the webapp β enter the key β Connect β drag and drop a
.rpkfile β Install to band.
| App | Description | Source |
|---|---|---|
| Calculator | Calculator + β Γ Γ·, decimals | demo-apps/calculator |
| Drawing | Freehand drawing: 5 colours, 3 brush sizes, eraser, undo, autosave | demo-apps/drawing |
| Notes | Shows the user's notes (read-only). Notes are written in the webapp; the browser repacks and re-signs the .rpk and installs it |
demo-apps/notes + src/rpk/ |
| Checklist | Shopping, to-do and packing lists written in the webapp (repacked and re-signed in the browser like Notes); tap items on the band to tick them off, ticks saved on the band | demo-apps/checklist + src/rpk/ |
| Snake | Snake game: swipe or tap the left/right half to turn, speeds up, saves the high score | demo-apps/snake |
| SAT Flashcards | Learn 1,355 SAT words: flip cards (Know it / Again) or a multiple-choice quiz, spaced repetition (Leitner boxes), progress saved on the band | demo-apps/sat-flashcards |
| Flashcards | Your own decks (any subject or language), written or pasted from a spreadsheet in the webapp and repacked into the .rpk like Notes; flip cards or multiple-choice quiz, Leitner progress per deck saved on the band |
demo-apps/flashcards + src/decks/ |
| Metronome | Silent metronome: the beat as a vibration on the wrist plus a flash, 30β250 BPM, tap tempo, accent on beat 1 in 2/4, 3/4, 4/4, 6/8 | demo-apps/metronome |
| Counter | Tally counter: tap anywhere to count (short buzz), β1, reset with a confirming second tap, goal presets with a long buzz and a tick, four named counters saved on the band | demo-apps/counter |
| Random | Random number (min/max with β / +), dice (1 or 2 with the sum), coin flip; No repeats mode for raffles; buzz on each result, settings saved on the band | demo-apps/random |
Outside the catalog: Phone Remote (demo-apps/phone-remote) β press on the band to take photos, change slides, play/pause on the phone. It needs the companion Android app (same package, same signature) and Mi Fitness to relay messages over system.interconnect; not yet verified on Mi Band 9/10, so it is not in the catalog yet.
All catalog apps are built with aiot-toolkit 2.0.5 (Xiaomi Vela's official toolchain). None has been run on a real band yet.
src/rpk/ is a WebCrypto port of aiot-toolkit's "RPK Sig Block 42" signature format (a variant of APK Signature Scheme v2, RSA PKCS#1 v1.5 + SHA-256). Tests confirm the signature is byte-for-byte identical to the one the toolkit produces. Notes is signed with a demo key that is deliberately public (src/rpk/demo-key/).
worker/xiaomi-cloud.ts does a Xiaomi QR login for the Mi Fitness service (sid=miothealth, callback https://sts-hlth.io.mi.com/healthapp/sts):
/api/xiaomi/qr creates the QR code, then /api/xiaomi/poll long-polls until the user scans it and then:
- Mi Fitness: gets the service token and calls
POST https://hlth.io.mi.com/app/v1/source/get_source_listwithdata={"page_size":50,"status":1}(then the regional<region>.hlth.io.mi.comif a region is picked). The bound bands come back withdetail.encrypt_key/detail.auth_key(and sometimesdetail.token); every distinct 32-hex value is offered. Two request encodings are tried: the Mi Home one (params in the query, used by ha_miband, Apache-2.0) and a single RC4 stream over sorted params in the body (huami-token, MIT; AstroBox, AGPL-3.0). - Mi Home (only if no Mi Fitness key was found): signs in to
sid=xiaomiiowith thepassTokenof the same login (no second scan), lists devices and callsblt_get_beaconkey, as in Xiaomi Cloud Tokens Extractor (MIT).
The login session (ssecurity/serviceToken/passToken) only lives within a single Worker request: it is not returned to the browser, not stored, and observability is off.
A proxy is needed because Xiaomi's API does not let browsers call it directly (CORS is blocked).
Unverified here: the Mi Fitness route follows three independent open-source clients and Xiaomi's servers accept the
miothealthQR login, but this project has not yet run it against a real account with a band. The Mi Home route rarely helps for Mi Band 8/9/10, which are not Mi Home devices.
Fallbacks that need no cloud call (also in the page under Other ways and in docs/GUIDE.md):
- iPhone / iPad: Files β On My iPhone/iPad β Mi Fitness β Compress, then pick the zip in the page.
src/core/mifitness-files.tsreadsMHWCahe/<uid>/VirtualDevice_registerList/manifest.sqlite(+-wal) in the browser: a small SQLite reader, a binary-plist reader and NSKeyedArchiver unwrapping, takingencryptKeyfrom everyregisterList_<region>entry. Layout documented by xiaomi-band-ios-export (MIT, tested there with a Smart Band 10); tested here with synthetic fixtures only. - Android: the Mi Fitness logs in
Android/data/com.mi.health/files/log/containencryptKey=/token=(see Gadgetbridge and Gadgetbridge issues #4052, #4859).
Download what the band recorded (steps, heart rate, sleep, SpOβ, stress, workouts) as JSON, CSV or raw files, query it with your own AI agent through a local MCP server (tools/health-mcp) Nothing leaves your machine. Format, privacy and what is still untested: docs/health-data.md.
One Worker serves both the static page (dist/) and /api/*, on the custom domain miband.trinh.uk:
echo 'CLOUDFLARE_ACCOUNT_ID=<your id>' > .env # Wrangler reads this file itself; it is gitignored
npm run deployTo deploy to a different domain, edit routes in wrangler.jsonc.
The page is a PWA (manifest + service worker): users press "Install as app" to get their own icon, and it opens even offline (except for the key retrieval step).
npm install
npm run dev # http://localhost:5173 (Web Serial/Bluetooth work on localhost)
npm run dev:worker # also runs the Worker (/api/xiaomi/*) at http://localhost:8787
npm test # unit tests + integration tests against a simulated band
npm run build # static build to dist/, deploy to any HTTPS hostsrc/
core/ bytes, checksum (CRC16/ARC, CRC32), crypto (hand-written AES-CCM, AES-CTR, HMAC),
auth (miwear-auth handshake), proto (protobuf subset), packets (SPP V1/V2), files (.rpk/.bin)
transport/ serial.ts (Web Serial β RFCOMM SPP), ble.ts (Web Bluetooth, auto-detects BLE V1/V2)
protocol/ stream-link.ts (SPP V1/V2 + sliding window, used for both SPP and BLE V2),
ble-v1-link.ts (Mi Band 8 chunk protocol)
device.ts auth, device info, app/watchface lists, install (DataUpload)
main.ts UI (including the "Demo apps" catalog read from public/apps/catalog.json)
worker/ Cloudflare Worker: serves the page + the Xiaomi QR key API
demo-apps/ demo app sources (Calculator)
test/
core.test.ts crypto checked against node:crypto, frame/protobuf vectors, file parsing
fake-band.ts simulated band (band-side crypto uses node:crypto, independent of the main code)
integration.test.ts version probe β SPP V2 β auth β end-to-end .rpk install
Protocol details: docs/protocol.md. Real-device captures (Mi Band 10 with Mi Fitness on iOS: session config, binding flow, NO_BOUND): docs/captures/mi-band-10-ios.md; why the browser cannot bind such a band: docs/binding-research.md.
- Test on a real Mi Band 9/10 over Web Serial on macOS, Windows and Linux (the biggest risk, see the "Risks" section in the docs).
- Test Mi Band 8 and tune the BLE write size (default 180 bytes).
- App/watchface store (catalog + search + one-tap install).
- i18n (English / δΈζ).
- Confirm the Mi Fitness QR route (
get_source_list) and the iPhone/iPad folder route with a real account and band; note which key field (encrypt_key,token) the band accepts.
AGPL-3.0-or-later, because the protocol code is a port of Gadgetbridge (AGPL-3.0). The Xiaomi login flow is ported from Xiaomi Cloud Tokens Extractor (MIT); the Mi Fitness calls follow ha_miband (Apache-2.0), huami-token (MIT) and AstroBox (AGPL-3.0). See LICENSE.