Files

T

John O'Keefe b4b1deafb8 docs(user): Android app guide — LAN setup and the Android 16+ local-network permission

Android 16+ gates per-app access to local networks behind a runtime
permission; without it the app's LAN logins time out with zero packets
leaving the phone (browser works — it is not per-app-gated). The new
device guide covers the sideload install, first-run server URL, the
permission prompt (and manual re-grant path), and a triage table for
the login screen's error line. Per the user: overlay-VPN addresses are
not a consideration and stay undocumented.

2026-09-29 18:12:57 -04:00

2.9 KiB

Raw Blame History

Android App Setup Guide

The Bookhoard Android app is the native mobile client: browse your libraries, read EPUBs, PDFs, comics and manga, and sync progress, highlights, bookmarks and notes with the server.

Prerequisites

✅ A Bookhoard instance running and reachable from your phone's network
✅ The Bookhoard APK installed on your phone (Android 8.0+ / API 26+)
✅ Your phone connected to the same network as the server (for a self-hosted LAN setup)

Installing the app

The app is distributed as a sideloaded APK:

Copy the APK to your phone (USB, or any file-sync you trust)
Tap the APK to install — approve the "install unknown apps" prompt for the app you installed from (file manager, browser, etc.)
Upgrades install straight over the existing app and keep your data (login, downloads, reading state)

First run

Server URL — enter your server's address. For a self-hosted LAN setup that is http://<desktop-LAN-IP>:8765 (plain HTTP is expected here and fully supported; check the server machine's firewall allows port 8765 from your LAN)
Log in with your Bookhoard account
Device registration happens automatically — the app registers itself as a synced device so progress and annotations sync under your account

Android 16+: the local-network permission

On Android 16 and newer, apps need explicit permission to talk to devices on your local network (and to non-HTTPS local addresses in general). If the permission is missing, the app's logins to a LAN server time out with no visible cause — the phone silently drops the traffic.

The app asks for the permission by itself during setup, as soon as you enter a local server address — grant it when prompted
If it was denied (or you missed the prompt): Settings → Apps → Bookhoard → Permissions → "Access local network devices" → Allow, then try again
Servers reached over the public internet (HTTPS) are not affected by this permission

The login screen prints the underlying error after "Could not reach server: …" — read it to narrow the cause:

Error	Meaning	What to check
`SocketTimeoutException`	The phone sent nothing that reached the server	On Android 16+ this is most often the local-network permission (above). Otherwise: wrong IP, phone on a different network/VLAN, or server down
`ConnectException` (connection refused/blocked)	The phone reached the machine but nothing answered	Server container down, or a firewall rejecting port 8765
`UnknownHostException`	The hostname didn't resolve	Typo in the server URL, or a DNS/name issue (raw IPs avoid this)

To verify the server is reachable from the phone at all, open the same URL in the phone's browser — the browser is not subject to the per-app local-network permission, so if the browser works but the app times out on Android 16+, it is the permission.

2.9 KiB Raw Blame History