mc-webui/docs/android-app.md

mc-webui for Android

A small companion app that opens your own mc-webui instance full screen — no address bar, no browser tabs, its own icon in the app drawer. It looks and works like a native app, because underneath it is the same web interface you already use in the browser.

The app contains no mesh logic of its own: it asks once for the address of your mc-webui server and displays it. Everything still runs on your server and your MeshCore device.

There are two ways to get it. The app is published on Google Play, which is the simplest route and keeps itself updated. The signed .apk also stays in this repository for anyone who would rather not go through the Store — the same app, signed with the same key, so you can move between the two without uninstalling anything.

---

What you need

• Android 5.0 (Lollipop) or newer
• A running mc-webui instance the phone can reach — either on the same local network (e.g. http://192.168.1.100:5000) or published over the internet through a reverse proxy (e.g. https://mc-webui.example.com)

---

Install from Google Play

Store listing	https://play.google.com/store/apps/details?id=it.wojtaszek.mc.wrapper
Package	it.wojtaszek.mc.wrapper
App version	2.0

Open the listing on the phone and tap Install. Updates then arrive on their own, like for any other app from the Store. Skip straight to Step 4: Connect to your instance below — the warnings in steps 2 and 3 apply only to the manual route.

Already running the .apk from this repository? Installing from Play updates it in place. The server address and any saved login are kept, and nothing needs uninstalling — both builds are signed with the same key, which is exactly what makes that possible. Moving the other way works too.

---

Or install the .apk yourself

The rest of this section is the manual route — useful if you avoid the Play Store, want a specific version, or would rather verify what you install. It is a normal and supported way to install Android apps, but Android will warn you a few times along the way, and the steps below cover those warnings.

---

Step 1: Download the app

File	android/mc-webui-wrapper.apk
Direct link	https://github.com/MarekWo/mc-webui/raw/main/android/mc-webui-wrapper.apk
Size	5.2 MB
App version	2.0
Package	it.wojtaszek.mc.wrapper
SHA-256	165706d8c8fa0ef9c1095027efaeff863c41681e059be8cc631dd735c0c21f3f

Download it directly on the phone, or copy it over from a computer.

Optional — verify the file. Only worth doing if you got the file from somewhere other than this repository:

# Linux / macOS
sha256sum mc-webui-wrapper.apk

# Windows (PowerShell)
Get-FileHash mc-webui-wrapper.apk -Algorithm SHA256

The result must match the SHA-256 above.

---

Step 2: Allow installation from unknown sources

Android only installs apps from Google Play unless you allow the app that is doing the installing — usually your browser or the Files app — to install others. You grant that permission once, and it applies to that app only.

The easy way — just start the installation (Step 3). When Android says "For your security, your phone is not allowed to install unknown apps from this source", tap Settings, turn on Allow from this source, and press back. The installation continues.

Up front, if you prefer — Settings → Apps → Special app access → Install unknown apps → pick the browser or file manager you will use → Allow from this source. The exact wording varies by manufacturer (Samsung, Xiaomi, and others each name it slightly differently).

---

Step 3: Install

1. Open the downloaded mc-webui-wrapper.apk — from the browser's download notification, or from Files → Downloads
2. Tap Install
3. Play Protect may show "Unsafe app blocked" or "App scan recommended". This is Google's standard notice for apps that did not come from the Play Store — it is not a detection of anything in the app. Choose More details → Install anyway (or Don't send / Install if it offers to upload the file for scanning)
4. Tap Open, or launch mc-webui from the app drawer

To remove it later: long-press the icon → Uninstall, like any other app.

---

Step 4: Connect to your instance

On the first run the app asks for the address of your server:

Type the full address, including the protocol and — for a local instance — the port:

Your setup	What to enter
mc-webui on the local network	http://192.168.1.100:5000
Behind a reverse proxy with a certificate	https://mc-webui.example.com
On a non-standard port behind a proxy	https://mc-webui.example.com:8443

Then tap SAVE & CONNECT.

Type http:// explicitly for local instances. If you leave the protocol out, the app assumes https:// and the connection to a plain local server will fail.

The address is remembered, so every later launch goes straight into mc-webui.

Changing the address later

Press Back on the first mc-webui page and the app asks what you want: Change server brings up the address form, Exit closes the app, Cancel stays where you were. (Deeper inside the interface, Back simply goes back a page, as in a browser.)

The address form also appears on its own when the app cannot reach the server — wrong address, server down, phone off the network. Either way the form opens pre-filled with the address you are using, and nothing is overwritten until you tap SAVE & CONNECT: a dropped connection never costs you the address.

Switching between several servers

From version 2.1 the form also lists the servers you have reached before, under Recent servers. Tap one and the app connects to it straight away — no retyping, and any username and password saved for that server still apply, since those are remembered per address. The ✕ beside an entry drops it from the list; that only forgets the shortcut, never the server you are currently using or its saved login.

The list holds the six most recent addresses, newest first, and only ones that actually answered — a mistyped address never joins it. If you run a single instance you will simply see it listed there on its own, and nothing about the form changes.

Connecting to a server this way starts it fresh: Back brings up the leave prompt again rather than reversing into the pages of the server you just left. Otherwise the app would end up showing one instance while it is set to another.

Servers that ask for a password

If your instance sits behind a reverse proxy configured to require a login (HTTP Basic authentication — for example an Access List in Nginx Proxy Manager), the app asks for it the first time it connects, from version 1.3:

Enter the username and password your proxy expects and tap SIGN IN. They are remembered per server address, so later launches go straight in. Get them wrong and the same prompt comes back on the next attempt, with the username filled in. Tapping Cancel returns to the address form.

This only ever appears when the server actually asks for a password. On an instance without one — local http:// or a proxy with no access control — you will never see this screen, and nothing about the app changes.

Turning the password on, or changing it, while the app is open. The prompt comes up when the app loads a page, not when a request it makes in the background is refused. So if you switch authentication on — or change the password — with the app already running, it keeps trying the old credentials and the interface stops updating rather than asking you anything. Close the app and open it again, and it will ask properly.

---

What works, and what doesn't

Everything you do in mc-webui itself works as in the browser: channels, direct messages, contacts, the console, My Repeaters, the Path Analyzer, maps, settings, themes. Links to other sites — a URL in a message, the packet analyzer — open in your normal browser, so the app stays on your instance.

A couple of things depend on how your instance is reachable:

Feature	In the app
Notifications for new messages	Work, from version 1.1, and keep working in the background from version 2.1 (see below). Turn them on in the mc-webui menu as usual; Android asks for its own permission the first time. Unlike a browser, these also work over plain http://. Tapping one opens the conversation it came from
Scanning a QR code (Add Contact → Scan QR)	Works on https:// instances. Android asks for camera permission the first time. Over plain http:// the camera stays blocked — that is a browser rule, not an app limitation, and Chrome on the same phone behaves identically. Use Paste URI or Manual entry there
Downloading files (e.g. database backups)	Works. Files land in the phone's Downloads folder, with the usual download notification
HTTPS with a self-signed certificate	Refused, with an "SSL error" message. Use a valid certificate (e.g. Let's Encrypt), or plain http:// on the local network

Notifications while the app is in the background

Up to version 2.0 alerts went quiet a few minutes after you switched away from the app. That was Android, not a setting anyone had got wrong: an app with nothing running in the foreground is eventually frozen to save memory, and a frozen app holds no connection to your server and runs no code to alert you with. No battery option prevents that — "Unrestricted" exempts an app from Doze and battery optimisation, which are a different mechanism entirely.

From version 2.1 the app asks Android to leave it running, which Android grants in exchange for a permanent notice in the shade saying it is doing so:

Listening for new messages — mc-webui stays connected while you are in another app, so new messages still reach you.

That notice is silent, sits at the bottom of the shade, and only appears once you turn notifications on in mc-webui itself. Turn them off there and it goes away with them. Its Stop button ends it for the rest of the session, without changing any setting — opening the app again brings it back.

It can also be silenced on its own, in Android Settings → Apps → mc-webui → Notifications, where it appears as the Background delivery category separate from Mesh activity. Turning that category off stops the notice from showing, and Android then stops keeping the app alive too — so message alerts go back to arriving only while the app is open.

Nothing about this sends anything anywhere: the connection being held open is the one to your own server, and the alerts are still built by the mc-webui page itself, which is why mutes, blocked senders and channel names all behave exactly as they do in a browser tab.

---

Security notes

• Install the app from Google Play, or the .apk only from this repository (or from the project's GitHub Releases page). An .apk from anywhere else is a different app, no matter what it is called
• The app stores two things on the phone: the server address you typed, and — only if your server asks for a login — the username and password for it. Both live in the app's private storage, which no other app can read. No messages, keys, or contacts — those stay on your server and your MeshCore device
• Plain http:// is allowed so that local instances work without a certificate. On a home network that is fine; over the internet, put mc-webui behind a reverse proxy with HTTPS and some form of access control. The app has no login of its own, but it does support a proxy that requires one (see Servers that ask for a password above) — and over https:// those credentials are encrypted in transit like everything else
• Permissions: internet access; the camera, only when you use QR scanning and only after you allow it; notifications, only after you turn them on in the menu and allow them; from version 2.1 a foreground service, started only while those notifications are on, so they keep arriving in the background (it shows a permanent notice for as long as it runs, and holds open the connection to your own server — nothing else); and file storage on Android 9 and older, only for saving a download. Nothing else — no contacts, no location, no analytics
• Every release is signed with the same key — the Play build included, because the key was registered with Play App Signing rather than letting Google generate its own (certificate SHA-256 42:58:57:b3:60:0c:1b:89:2f:8d:3b:2a:5c:46:8b:fe:17:c0:d2:1f:6c:12:24:33:a4:e1:1b:51:be:9b:d2:30), which is also why updates install straight over the previous version

---

How it is built

A minimal Android WebView wrapper: one screen for the server address, one full-screen WebView for mc-webui itself, and a saved preference between them. No analytics and no third-party services. The one thing that runs outside the screen is the foreground service described above, which does no work of its own — it exists purely so Android leaves the page running — and only exists while notifications are switched on. Close the app and nothing of it runs.

The complete source is in android/src/, and android/README.md describes how to build it yourself if you would rather not trust a prebuilt .apk.

---

See also

• Privacy Policy — what the app stores on the phone, and why none of it ever reaches anyone but your own server
• User Guide — everything the interface itself can do
• PWA Notifications — how the same notifications behave in the browser
• Troubleshooting — when the server itself misbehaves