Unraid Manager is a native Android monitoring and operations console for Unraid.
Current source version: v0.19.0 · Android 8.0 (API 26) or newer.
The app is designed around three rules: show whether the server is healthy at a glance, keep read-only monitoring useful when the server is temporarily unreachable, and make every supported write operation explicit and verifiable.
-
Native OpenCanary security dashboard with 24-hour, 7-day, 30-day, and all-time views.
-
Home security card showing recent event count, source count, and connection state.
-
A dedicated high-priority Android notification channel with stable event deduplication.
-
A 15-minute WorkManager security check independent of the slower host-health schedule.
-
The existing unified Unraid API key also authenticates OpenCanary; no second key is stored.
-
The bundled dashboard validates every key against local Unraid GraphQL. Anonymous public event access is rejected, and the browser keeps the key only in memory for the current page.
-
Persistent encrypted login: a successful connection is restored after a cold start instead of returning to the login screen.
-
Multiple server profiles with per-server credentials, settings, dashboard layout, favorites, shortcuts, alert settings/state, operation history, cache, and trends.
-
Primary and alternate Unraid addresses with automatic last-known-good endpoint fallback and reconnect after Android network recovery.
-
Offline snapshots with a visible stale-data timestamp. Cached data is read-only; Docker writes are blocked until a live connection is restored.
-
Explainable health assessment plus 24-hour and 7-day CPU, memory, storage, UPS, and Docker trends.
-
Reorderable and hideable home sections: alerts, health, resources, storage, Docker shortcuts, UPS, services, and recent operations.
-
Docker favorites, sorting, native icons, live resource statistics, separate update-check and update buttons, explicit confirmation, and post-action verification.
-
Native XFileManager-backed file browser with previews, share links, and foreground upload and download tasks that support cancel and retry.
-
UPS discovery through an HTTPS UPS Bridge, private-network NUT, or compatible Unraid GraphQL UPS data, with the actual source and failure reason shown in the app.
-
Real VM telemetry through the same read-only Bridge: live CPU and memory, configured vCPU and memory, CPU pinning, disk paths/capacity/allocation, interfaces, MAC addresses, and discoverable IPs.
-
Android home-screen status widget for the active server, plus background checks, actionable notifications, recovery notices, and quiet hours.
See the Chinese usage guide for setup instructions and dependency details. Release-specific changes and limitations are in the v0.19.0 release notes.
- Install the
v0.19.0APK from the matching release. - Add a server name, a reachable Unraid URL, and one Unraid API key.
- Use HTTPS for remote access. Documentation-only examples are
https://unraid.example.testandhttp://192.0.2.10. - Grant only the permissions needed for the intended mode:
- monitoring only:
role:viewerand select read-only mode in the app; - Docker and VM operations:
role:viewer,docker:update,vms:updateand keep operations mode enabled.
- monitoring only:
- Grant Android notification permission if background alerts or visible file-transfer progress are required.
The unified Unraid API key is used for Unraid GraphQL and, when configured, for UPS Bridge authorization. XFileManager is a separate service and therefore requires its own dedicated, low-privilege account.
Each profile can store a primary URL and an alternate URL:
- Auto tries the last successful endpoint, then the primary URL, then the alternate URL.
- Primary uses only the primary URL.
- Alternate tries the alternate URL first, then the primary URL as fallback.
When all live endpoints fail, the app can display the latest local snapshot and its capture time. Offline or stale data never enables write operations. Local snapshots and metric samples are kept for up to eight days; the 24-hour and 7-day charts fill as the app and background checks collect real samples.
| Feature | Requirement |
|---|---|
| Unraid monitoring | Reachable Unraid GraphQL API and a Viewer-capable API key |
| Docker operations | docker:update, operations mode, a live connection, and explicit confirmation |
| VM operations | vms:update, operations mode, a live connection, and explicit confirmation |
| Native file module | A reachable compatible xfilemanager-app service and a dedicated account |
| Real VM telemetry | Read-only Bridge 1.1.1, Unraid VM Manager/libvirt, and the read-only libvirt socket |
| HTTPS UPS data | The same Bridge, local NUT data, and a reverse proxy preserving x-api-key |
| Raw NUT fallback | Direct private-LAN/VPN reachability to TCP 3493; never expose it publicly |
| UPS API fallback | An Unraid/UPS plugin combination that returns UPS devices through GraphQL |
| Background alerts | Android background work enabled; Android 13+ also requires notification permission |
| OpenCanary alerts | Authenticated dashboard API, HTTPS reachability, and the same Viewer-capable Unraid API key |
| Home widget | Add “Unraid Status” from the Android launcher; it shows the active profile only |
“Check updates” and “Update” are intentionally separate. Direct update is available only for an eligible single container after an update has been confirmed and a DockerMan template is present. The app requires confirmation, asks Unraid to rebuild from the template, and verifies the resulting image and expected running state.
This is not an automatic rollback system. Unraid may delete an unreferenced old image during the native update flow, and the app does not snapshot appdata, volumes, databases, templates, or array data. Pre-update image/template information is diagnostic recovery metadata, not a restorable backup. Keep independent appdata and configuration backups and use Unraid's own tools for a manual restore when required.
Docker delete and bulk update remain unavailable. VM start, graceful stop, pause/resume, and reboot are available; force-stop, reset, delete, and configuration changes remain unavailable.
The file screen is native Android UI; it is not a WebView and it does not use SSH or SFTP. It calls
the JSON API of xfilemanager-app, so the module cannot work without that service.
Transfers run as constrained WorkManager foreground tasks. Downloads can continue through HTTP Range when the server accepts it. A failed upload is retried from the beginning because the current service API does not provide chunk-resume semantics. Android's document picker is used for local files, so the app does not request broad storage access.
UPS sources are attempted in this order:
- configured UPS Bridge endpoint;
- raw NUT on TCP 3493 only for private/local Unraid hostnames or addresses;
- the complete Unraid UPS GraphQL query;
- a compatibility UPS-device query.
Bridge 1.1.1 validates the existing Unraid API key against local GraphQL and stores no key on disk.
Its UPS endpoint issues only NUT LIST UPS and LIST VAR; its VM endpoint uses virsh -r through
/var/run/libvirt/libvirt-sock-ro. It implements no VM or UPS write endpoint. The APK derives /vms
from the configured UPS status URL, so one API key, one backend port, and one Lucky path serve both.
For public access, publish only the bridge path through HTTPS; do not expose TCP 3493, the libvirt
socket, or the bridge's private backend port.
The OpenCanary module reads GET /api/events from the user-configured dashboard URL and sends the
same x-api-key already used for Unraid. The bundled dashboard validates that key against local
GraphQL and stores neither the key nor attack-event credentials. Its browser page requires the key
for each page load and keeps it only in memory.
Android background checks run no more frequently than the WorkManager minimum of 15 minutes and may be delayed by battery optimization. Unraid's own notification command remains the immediate primary alert path; the APK notification is a mobile supplement. The first successful APK poll establishes a baseline and does not replay historical events. Later events are deduplicated by a stable event ID and open the native security page when tapped.
- No analytics, advertising, telemetry, crash reporting, or behavior-tracking SDK is included.
- API keys and the XFileManager password are encrypted with AES-GCM keys held by Android Keystore.
- Android cloud backup and device-transfer extraction are disabled for the app.
- Cached snapshots do not contain API keys, file credentials, or container logs. Error and log text is passed through sensitive-value redaction before display or persistence.
- Local XFileManager share records include the server-generated URL, which may contain a share token. They stay in app-private storage; removing a local record does not revoke the server link.
- The app connects to user-configured Unraid, XFileManager, and UPS endpoints. An explicit enhanced Docker update check may also contact the public registry named by a container image and its anonymous token service.
- Cleartext HTTP remains supported for trusted LAN deployments. Remote access should use a valid system-trusted HTTPS certificate or a trusted VPN.
- The Android permissions are limited to Internet/network state, notifications, and foreground data-sync service support. No location, contacts, microphone, camera, SMS, root, or broad-storage permission is requested.
Read SECURITY.md before deploying the app outside a trusted network.
Requirements:
- JDK 17 or newer
- Android SDK 36
On Windows PowerShell:
$env:ANDROID_HOME="$env:LOCALAPPDATA\Android\Sdk"
$env:ANDROID_SDK_ROOT=$env:ANDROID_HOME
.\gradlew.bat testDebugUnitTest lintDebug assembleDebug assembleReleaseBuild outputs:
- debug:
app/build/outputs/apk/debug/app-debug.apk; - release:
app/build/outputs/apk/release/app-release.apk.
Before distributing an APK, verify its manifest, signer, and SHA-256 with Android SDK aapt,
apksigner, and Get-FileHash. The compatibility APK intentionally keeps the Android
Debug certificate used by the public v0.15.3 build so Android can perform an in-place upgrade.
It is published as a GitHub prerelease, not as an app-store or production-signing build. Its signer
certificate SHA-256 is
ad0312960d166300a9b6c259bbc46e4ce9e500d87a5abba9fc1584c01a63f105.
A clone built with another machine's debug keystore will have a different signer even if the source is identical. Do not publish such a build as an upgrade, and never commit or share the maintainer keystore or its passwords.