Everything you need to get a server connected, and what to do when one won't.
You need three things: the address of the machine, whether it answers on HTTP or HTTPS, and an API token. The app never asks for your login password.
.invalid, so a demo build can't be
pointed at a real machine by accident.
Homelab software is inconsistent about TLS, so the scheme is a per-server choice rather than something the app assumes:
| Platform | Default |
|---|---|
| Proxmox VE | HTTPS only, port 8006 |
| TrueNAS SCALE | Either — HTTP on 80 unless you've configured TLS |
| Unraid | HTTP on port 80 unless you've configured TLS |
Proxmox tokens are created with Privilege Separation ON,
which means the token holds no permissions of its own — even one belonging to
root@pam. The result is a server that connects and reports
"online" with every statistic blank. This is the single most common Proxmox
setup failure, and the app detects the shape and tells you.
Run once as root on any node. In a cluster the users and ACLs replicate to the rest.
pveum role add HomelabDeck --privs "Sys.Audit,Sys.Console,VM.Audit,VM.PowerMgmt,VM.Console,Datastore.Audit"
pveum user add homelabdeck@pve --comment "Homelab Deck"
pveum acl modify / --users homelabdeck@pve --roles HomelabDeck
pveum user token add homelabdeck@pve ios --privsep 0No control, no console. Nothing in the app can change your infrastructure.
pveum role add HomelabDeckRO --privs "Sys.Audit,VM.Audit,Datastore.Audit"
pveum user add homelabdeck@pve --comment "Homelab Deck"
pveum acl modify / --users homelabdeck@pve --roles HomelabDeckRO
pveum user token add homelabdeck@pve ios --privsep 0Grant the role directly to the existing token instead of rebuilding it.
pveum acl modify / --tokens 'root@pam!yourtoken' --roles HomelabDeckProxmox will not open a console for an API token. Every
console endpoint — termproxy, vncshell,
vncwebsocket — rejects token authentication outright; they need
a ticket session, which means an account with a password. Granting
VM.Console is necessary and not sufficient on its own.
So console access is opt-in and stored separately. On the server's screen
in the app, open Edit → Console access and add a username
(with its realm, like homelabdeck@pve) and password. It lives in
the iOS Keychain, is used for nothing but opening a console, and everything
else on the server keeps working if you never add one — the console controls
simply don't appear.
Prefer a dedicated account with only VM.Console — and
Sys.Console if you want a node shell — over root@pam.
An account with two-factor authentication enabled can't be used: Proxmox
returns only a partial ticket and the app has no way to complete the second
step.
A VM also needs a serial port. Add one under the VM's Hardware tab in Proxmox and configure the guest OS to use it. Containers and the node shell need no setup.
| Privilege | Unlocks | Required |
|---|---|---|
Sys.Audit | Node status, CPU, memory, uptime, and the disk list with SMART health | Yes |
VM.Audit | The VM and container list with state and live metrics | Yes |
Datastore.Audit | Storage pools with capacity and health | Yes |
VM.PowerMgmt | Start, shut down, restart and force stop | Only for control |
VM.Console | A terminal on a VM or container | Only for the console |
Sys.Console | A root shell on the Proxmox host itself | Only for the node shell |
homelabdeck@pve!ios.--privsep 0 lets the token inherit the user's role. With privilege separation on, the token needs an ACL entry of its own.pveum role modify and pveum user modify instead of add.TrueNAS API keys inherit the permissions of the user that owns them, so the account matters more than the key. A non-privileged user is enough for the dashboard; starting and stopping needs an account that could do the same thing in the web UI.
Credentials → Local Users → your user → API Keys. On releases before 24.10 it's Settings → API Keys. Copy the key when it's shown — it is not shown again.
TrueNAS 25.10 removed the built-in SMART test scheduler, so no self-test runs unless you schedule one — and without a test, no SMART alert can ever fire. Add these under System → Advanced → Cron Jobs. Results arrive automatically as TrueNAS alerts; there's nothing else to install.
# Short test — weekly is plenty
midclt call disk.smart_test SHORT '[["*"]]'
# Long test — monthly
midclt call disk.smart_test LONG '[["*"]]'/alert/list, so it inherits every check iXsystems
adds rather than chasing endpoints as they move. Alerts you've
dismissed in TrueNAS are skipped here too.Unraid 7 exposes a GraphQL API through unraid-api. The key
carries its own permissions, granted when you create it.
Settings → Management Access → API Keys, or from the console:
unraid-api apikey --createIf the app can't connect at all, confirm the service is up before suspecting the key.
unraid-api statusCheck that iOS has granted the app local network access: Settings → Homelab Deck → Local Network. When it's off, iOS blocks LAN connections silently, which looks exactly like every host being down.
You're almost certainly pointing HTTPS at a server that only speaks cleartext. Edit the server and set the connection to HTTP. Unraid in particular serves on port 80 by default.
Proxmox: the token has Privilege Separation on and holds no permissions
of its own. Grant it a role on path /, or recreate it with
--privsep 0. See the Proxmox section.
Other platforms: the account owning the key can't read those endpoints. The app records why each fetch failed and surfaces it as a concern, so check the concerns list for the specific message.
The certificate changed. That's a hard failure by design — a silently accepted new certificate is indistinguishable from someone intercepting the connection. Remove the server and add it again, comparing the new fingerprint against the one the server's web UI shows.
The token is read-only. On Proxmox, add VM.PowerMgmt to its
role. On TrueNAS and Unraid, the key needs to belong to an account that can
start and stop things in the web UI. This is deliberate — a read-only token
is a supported configuration, and the dashboard works fully without control.
Proxmox accepts a task and runs it asynchronously; the app polls for up to 25 seconds. Past that it says the task is still running rather than claiming success or failure, because it genuinely doesn't know yet. Refresh in a moment to see the outcome.
If no passcode is set, or biometrics are locked out after failed attempts, control drops to confirmation-only rather than becoming unreachable. That's intentional — being locked out of your own infrastructure because of a biometric hiccup is worse than a confirmation sheet.
Once you have authenticated, biometrics stay unlocked for five minutes. The window closes as soon as the app leaves the foreground.
On 25.10, disks in a pool report live ZFS status, so this shouldn't happen for pool members. For SMART-specific alerts, no self-test has ever run — schedule one with the cron commands above. An alert can't fire without a test behind it.
A full refresh makes a lot of calls: on TrueNAS, alerts, reporting, temperatures and pool topology; on Proxmox, a version check plus one config lookup per stopped guest. On a large fleet this adds up. Reducing it is known work in progress.
Most stopped guests are stopped on purpose, so a stopped guest raises
nothing by itself. The alert fires when the platform's own auto-start flag is
set and the guest isn't running — Proxmox onboot, TrueNAS
autostart, Unraid autoStart. It's deliberately not a
setting inside the app: it's your declaration, on your own server, so it can't
drift out of sync with reality.
Templates are excluded everywhere — they're permanently stopped by design. Where a platform doesn't report an auto-start flag at all (TrueNAS apps, Unraid VM domains), nothing is raised; unknown is never treated as a problem.
One known trade-off: onboot means "start when the host boots",
not "should be running right now". A guest stopped for maintenance will be
flagged until it comes back.
Concerns come in two weights. Warnings and above are things to act on — they colour the server badge and are what "N things need attention" counts. Advice appears in the list under a calmer heading but leaves a healthy server looking healthy.
The main advisory is ZFS fullness past 80%: write performance degrades as the allocator moves from first-fit to best-fit, before the pool is actually short of space and below TrueNAS's own 85% alert.
Long-press a concern you've looked at and decided to live with. It moves to a collapsed card at the bottom of the dashboard and stops counting toward the badge and the fleet header.
Two things break back through an acknowledgement:
Acknowledgements are per-server, and removing a server forgets them — so a re-added server doesn't arrive pre-silenced.
Every alert threshold is adjustable in Settings, and the defaults reproduce the app's behaviour exactly, so an untouched install is unchanged.
Three platforms are supported today, and which one gets built next is decided by what people ask for. There's no tracker to sign up to and no account to create — it's an email, and it reaches the person who writes the app.
Running something that isn't Proxmox, TrueNAS or Unraid — XCP-ng, Synology, Harvester, plain Docker, something else entirely? Say so. Adding a platform is a contained job, because every platform in the app is an adapter behind one shared interface.
Missing something on a platform that's already supported — a metric, a control, a screen, a notification? Those are usually smaller and land sooner.
Both buttons open your mail app with a few prompts already filled in. Answer what you can and delete the rest — a one-line request is still worth sending. If the buttons don't work, mail [email protected] directly.
Email [email protected]. It's a small operation, so please include:
Never send an API token, a password, or a screenshot with one visible. Nothing about diagnosing a problem requires it.