Support

Adding your first server

You need three things: the address of the machine, whether it answers on HTTP or HTTPS, and a credential. Most platforms issue a scoped API token for this; two of them have no such thing and use an account instead, which is called out where it applies.

Every platform at a glance

1. Create an API token on the server — the sections below give the exact commands per platform.
2. In the app, tap Add Server, pick the platform, and enter the address, port and token.
3. If the server uses a self-signed certificate, the app shows you its fingerprint. Compare it against the one your server's own web UI displays, then trust it.

HTTP or HTTPS?

Homelab software is inconsistent about TLS, so the scheme is a per-server choice rather than something the app assumes:

Proxmox VE

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.

Everything, including console access

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,VM.Config.Options,VM.Config.CPU,VM.Config.Memory,VM.Config.Network,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 0

Read-only dashboard

No 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 0

Adding the edit privileges to a role you already made

Editing a guest — start-on-boot, CPU, memory, network — needs privileges an earlier role won't have. --append adds them without disturbing what's already there.

pveum role modify HomelabDeck --privs "VM.Config.Options,VM.Config.CPU,VM.Config.Memory,VM.Config.Network" --append

Proxmox's own error for this lists every privilege the endpoint will accept, including VM.Config.Disk. The app never edits disks and doesn't need it — grant only the four above.

Already made a token that isn't working?

Grant the role directly to the existing token instead of rebuilding it.

pveum acl modify / --tokens 'root@pam!yourtoken' --roles HomelabDeck

The console needs a password as well as a privilege

Proxmox 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. Proxmox adds none by default, so termproxy answers "unable to find a serial interface" on a stock VM. Add a Serial Port under the VM's Hardware tab and configure the guest OS to use it — on Debian and most Linux guests that means enabling a getty on ttyS0. Containers and the node shell need none of this and work straight away.

Windows guests cannot use a serial console at all, with or without the port. There is no text console to attach to; a graphical console is the only option, and that is not in the app yet.

What each privilege buys

• The last command prints the secret once. It cannot be shown again.
• Enter the Token ID in full, including user and realm — 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.
• The commands are not idempotent. If the role or user already exists, use pveum role modify and pveum user modify instead of add.
• API tokens need Proxmox VE 6.2 or newer. Support in this app starts at 7.0.

What the Proxmox VE credential needs

Proxmox tokens start with Privilege Separation ON, which means the token holds no permissions of its own — even a token belonging to root@pam. That produces a server that connects and reports "online" with every statistic blank. Grant a role at path / and it works.

Everything, including console access

Run once on any node. Creates a dedicated user rather than using root.

pveum role add HomelabDeck --privs "Sys.Audit,Sys.Console,VM.Audit,VM.PowerMgmt,VM.Console,VM.Config.Options,VM.Config.CPU,VM.Config.Memory,VM.Config.Network,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 0

Read-only dashboard

No 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 0

Lost the secret? Regenerate it

The secret is shown once and cannot be retrieved — reinstalling the app, moving to a new phone or starting over all end here. Remove the token and add it back under the same name: the user, role and ACL are untouched, and the Token ID you type stays the same.

pveum user token remove homelabdeck@pve ios
pveum user token add homelabdeck@pve ios --privsep 0

Adding the edit privileges to a role you already made

Editing a guest needs privileges the earlier role didn't include. --append adds them without disturbing what's already there.

pveum role modify HomelabDeck --privs "VM.Config.Options,VM.Config.CPU,VM.Config.Memory,VM.Config.Network" --append

Already made a token that isn't working?

Grant the role directly to the existing token instead of rebuilding it.

pveum acl modify / --tokens 'root@pam!yourtoken' --roles HomelabDeck

• The last command prints the secret once. It cannot be shown again.
• Enter the Token ID here in full, including the user and realm — homelabdeck@pve!ios.
• --privsep 0 lets the token inherit the user's role. With privilege separation on, the token needs its own ACL entry of its own.
• Run it as root on any one node. In a cluster the users and ACLs replicate to the rest.
• API tokens need Proxmox VE 6.2 or newer. On older releases, create a user and use password auth.
• The commands are not idempotent — if the role or user already exists, use `pveum role modify` and `pveum user modify` instead of `add`.

Proxmox Backup Server

Proxmox Backup Server is a separate product from Proxmox VE, with its own API on port 8007. If PBS runs on the same machine as PVE, add it as a second server here — the port is what tells them apart.

There are no VMs or containers to show, because PBS runs nothing. What it answers is whether your backups are actually working, and the check that matters most is one nothing else can see: a backup job that quietly stopped running. Nothing fails, the datastore has room, the guest is up — the only symptom is that the newest snapshot keeps getting older. The app flags anything not backed up for two days, and escalates it after six.

Roles and privileges are not the same thing

This trips people up, so it's worth being precise. PBS grants roles to an auth ID at a path. A role is a named bundle of privileges. You grant roles; proxmox-backup-manager acl update will reject a privilege name.

So acl update /datastore DatastoreAudit is correct, and acl update /datastore Datastore.Audit is not.

What the app calls, and what each call needs

Every one of these is read-only. Nothing in the app can create, change, prune or delete a backup. Paths are relative to /api2/json.

PBS returns only the datastores your token can audit, so a missing grant looks like an empty list rather than an error. The app treats that as something worth saying: if it can read the server but sees no datastores, or can't read a store's backup groups, it reports that with the privilege you need rather than showing a reassuring "no problems".

Scoping the path to a single datastore narrows what the app can warn you about as well as what it shows: backup freshness is only checked for stores the token can audit.

• PBS scopes ACLs in its own namespace — /datastore and /system. A Proxmox VE-shaped grant at / silently does nothing here.
• Support starts at PBS 2.0, which is where API tokens arrived.

What the Proxmox Backup Server credential needs

Proxmox Backup Server is a separate product from Proxmox VE, with its own API on port 8007. If PBS runs on the same machine as PVE, add it as a second server here — the port is what tells them apart. There are no VMs or containers to show: PBS runs nothing. What it answers is whether your backups are actually working.

A read-only account and token

Run once on the PBS host. Creates a dedicated user rather than using root, then grants the two audit roles to the user and to the token — both, because a token can never see more than its user.

proxmox-backup-manager user create homelabdeck@pbs --comment "Homelab Deck"
proxmox-backup-manager user generate-token homelabdeck@pbs ios
proxmox-backup-manager acl update /datastore DatastoreAudit --auth-id homelabdeck@pbs
proxmox-backup-manager acl update /system Audit --auth-id homelabdeck@pbs
proxmox-backup-manager acl update /datastore DatastoreAudit --auth-id 'homelabdeck@pbs!ios'
proxmox-backup-manager acl update /system Audit --auth-id 'homelabdeck@pbs!ios'

Check what the token can actually see

Empty braces mean the grants did not take — almost always the user half is missing.

proxmox-backup-manager user permissions 'homelabdeck@pbs!ios'

Lost the secret? Regenerate it

The secret is shown once and cannot be retrieved — reinstalling the app, moving to a new phone or starting over all end here. Delete the token and generate it again under the same name, so the Token ID you type stays the same. Unlike Proxmox VE, deleting a PBS token also deletes the ACLs granted to it, so the two token grants have to go back — the user's own grants are untouched.

proxmox-backup-manager user delete-token homelabdeck@pbs ios
proxmox-backup-manager user generate-token homelabdeck@pbs ios
proxmox-backup-manager acl update /datastore DatastoreAudit --auth-id 'homelabdeck@pbs!ios'
proxmox-backup-manager acl update /system Audit --auth-id 'homelabdeck@pbs!ios'

Granting only one datastore

Scope to a single store instead of all of them — again for the user and the token.

proxmox-backup-manager acl update /datastore/mystore DatastoreAudit --auth-id homelabdeck@pbs
proxmox-backup-manager acl update /datastore/mystore DatastoreAudit --auth-id 'homelabdeck@pbs!ios'

• The token secret is shown once, when the token is generated. It cannot be retrieved afterwards.
• Enter the token ID in full, including the realm and the token name — like homelabdeck@pbs!ios.
• A token's permissions are capped by its user's. Granting only the token — as this guide once said to — leaves a freshly created user with nothing, so the token sees nothing: the datastore list is empty and status and disks answer 403. Grant both.
• ACL changes take a few seconds to apply; a 403 straight after granting is not yet a failure.
• Deleting a token deletes every ACL granted to it. Regenerating a lost secret therefore needs the token's two grants again; the user's own grants survive.
• Nothing here can change or delete a backup. Both roles are read-only.
• If the server answers on HTTP but not HTTPS, set the connection to HTTP when adding it. Unraid serves its web UI on port 80 by default; Proxmox is HTTPS-only on 8006.
• Over HTTP your API token crosses the network unencrypted. That's a reasonable trade on a network you trust, and a bad one otherwise.
• Self-signed certificates are fine — the app shows you the fingerprint on first connect so you can compare it against the one the server's own web UI displays. After that a *changed* certificate is a hard failure until you approve it again.
• If the server has a real certificate — Let's Encrypt, or your own CA — add it by the name on that certificate rather than by its IP address. A certificate names hostnames, not addresses, so reaching it by IP fails the name check and drops you back to approving a fingerprint by hand — which you would then have to approve again at every renewal. By name it simply validates, and no fingerprint is ever shown.

TrueNAS SCALE

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.

Things that surprise people

• Disk health comes from ZFS, not from SMART self-tests. Each disk in a pool reports its live vdev status plus read, write and checksum error counters — that's the disk's state now, rather than the outcome of a test somebody may have run months ago. A disk ZFS still calls ONLINE while accruing checksum errors is reported as failing.
• Disks in no pool show "Not monitored". A boot device isn't part of a pool, so ZFS has nothing to say about it. That's honest rather than a failure to read it.
• 95% memory use is normal. ZFS ARC deliberately fills nearly all RAM. The bar shows the true figure, but the alert discounts reclaimable cache — otherwise it would fire forever on every healthy ZFS machine.
• SMART problems arrive as TrueNAS's own alerts. The app reads /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.

What the TrueNAS credential needs

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 can do the same thing in the web UI.

Create the key

Credentials → Local Users → your user → API Keys. On releases before 24.10 it's Settings → API Keys.

Copy the key when it is shown — it is not shown again.

Schedule SMART tests (25.10 and newer)

TrueNAS 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; nothing else to install.

# Short test — weekly is plenty
midclt call disk.smart_test SHORT '[["*"]]'

# Long test — monthly
midclt call disk.smart_test LONG '[["*"]]'

• Disk health comes from ZFS, so it is live rather than the result of a self-test. Disks that aren't in a pool show as "Not monitored".
• SMART problems arrive through TrueNAS's own alerts. TrueNAS 25.10 has no built-in SMART test scheduler, so nothing will raise a SMART alert unless you schedule tests yourself.
• Memory shows ZFS ARC separately. A TrueNAS box sitting at 95% memory is normal; the alert ignores reclaimable cache.
• If the server answers on HTTP but not HTTPS, set the connection to HTTP when adding it. Unraid serves its web UI on port 80 by default; Proxmox is HTTPS-only on 8006.
• Over HTTP your API token crosses the network unencrypted. That's a reasonable trade on a network you trust, and a bad one otherwise.
• Self-signed certificates are fine — the app shows you the fingerprint on first connect so you can compare it against the one the server's own web UI displays. After that a *changed* certificate is a hard failure until you approve it again.
• If the server has a real certificate — Let's Encrypt, or your own CA — add it by the name on that certificate rather than by its IP address. A certificate names hostnames, not addresses, so reaching it by IP fails the name check and drops you back to approving a fingerprint by hand — which you would then have to approve again at every renewal. By name it simply validates, and no fingerprint is ever shown.

Unraid

Unraid 7 exposes a GraphQL API through unraid-api. The key carries its own permissions, granted when you create it.

Create the key

Settings → Management Access → API Keys, or from the console:

unraid-api apikey --create

Check the API is actually running

If the app can't connect at all, confirm the service is up before suspecting the key.

unraid-api status

• Unraid's web UI is on port 80 over plain HTTP unless you've set up TLS, so most Unraid servers need the connection set to HTTP in the app.
• Unraid counts page cache as used memory, exactly like ZFS ARC. It gets the same two-segment treatment — real pressure and reclaimable cache shown separately.
• A server with virtualisation turned off returns usable data plus an error for the VM list. The app reports that as a warning rather than failing the whole refresh.

What the Unraid credential needs

Unraid 7 exposes a GraphQL API through unraid-api. The key carries its own permissions, granted when you create it.

Create the key

Settings → Management Access → API Keys, or from the console:

unraid-api apikey --create

Check the API is actually running

If the app cannot connect at all, confirm the service is up before suspecting the key.

unraid-api status

• Unraid's web UI is on port 80 over plain HTTP unless you've set up TLS, so most Unraid servers need the connection set to HTTP.
• Unraid's GraphQL field names changed between 6.12 and 7.x. If cards come back empty rather than erroring, the query needs updating for your build.
• If the server answers on HTTP but not HTTPS, set the connection to HTTP when adding it. Unraid serves its web UI on port 80 by default; Proxmox is HTTPS-only on 8006.
• Over HTTP your API token crosses the network unencrypted. That's a reasonable trade on a network you trust, and a bad one otherwise.
• Self-signed certificates are fine — the app shows you the fingerprint on first connect so you can compare it against the one the server's own web UI displays. After that a *changed* certificate is a hard failure until you approve it again.
• If the server has a real certificate — Let's Encrypt, or your own CA — add it by the name on that certificate rather than by its IP address. A certificate names hostnames, not addresses, so reaching it by IP fails the name check and drops you back to approving a fingerprint by hand — which you would then have to approve again at every renewal. By name it simply validates, and no fingerprint is ever shown.

Docker via Portainer

The app talks to Portainer, never to the Docker socket directly. The Docker socket has no authentication and no permission model — anything that can reach it is effectively root on the machine — so exposing it to a phone would be a bad trade. Portainer already has API keys and access control.

One Portainer server can front several Docker hosts. Its environments appear as this server's nodes, so a whole Docker fleet is one entry in the app.

Creating an access token

In Portainer: your username (top right) → My account → Access tokens → Add access token. It is shown once.

• A token inherits its user's permissions. A Read-only user gives a working dashboard that cannot change anything, which is a reasonable choice — start and stop then fail with a clear message rather than behaving oddly.
• Portainer serves HTTPS on 9443 and plain HTTP on 9000. The app defaults to 9443.
• A container Docker reports as restarting is in a crash loop. The app treats that as critical rather than as running — which is how it usually goes unnoticed.
• A container that exited with code 0 was stopped deliberately, or was a one-shot job that finished, and raises nothing. Only a non-zero exit is reported.

What the Portainer credential needs

Portainer sits in front of one or more Docker hosts, so one Portainer server here can cover your whole Docker fleet — its environments appear as this server's nodes. The app never talks to the Docker socket directly. That socket has no authentication at all, and anything able to reach it is effectively root on the machine.

Creating an access token

In Portainer: click your username (top right) → My account → Access tokens → Add access token. The token is shown once.

Portainer → My account → Access tokens → Add access token

Limiting what the token can reach

Tokens inherit the permissions of the user that made them, so make a dedicated user rather than using an administrator.

Portainer → Users → Add user
Portainer → Environments → your environment → Access → assign the user

• Portainer serves HTTPS on port 9443 and plain HTTP on 9000. The default here is 9443.
• A token inherits its user's permissions. A Read-only user gives a working dashboard with no ability to change anything — a reasonable choice.
• A container Docker reports as `restarting` is in a crash loop. The app treats that as a critical concern rather than as running, which is how it usually goes unnoticed.
• A container that exited with code 0 was stopped deliberately and raises nothing. Only a non-zero exit is reported.
• If the server answers on HTTP but not HTTPS, set the connection to HTTP when adding it. Unraid serves its web UI on port 80 by default; Proxmox is HTTPS-only on 8006.
• Over HTTP your API token crosses the network unencrypted. That's a reasonable trade on a network you trust, and a bad one otherwise.
• Self-signed certificates are fine — the app shows you the fingerprint on first connect so you can compare it against the one the server's own web UI displays. After that a *changed* certificate is a hard failure until you approve it again.
• If the server has a real certificate — Let's Encrypt, or your own CA — add it by the name on that certificate rather than by its IP address. A certificate names hostnames, not addresses, so reaching it by IP fails the name check and drops you back to approving a fingerprint by hand — which you would then have to approve again at every renewal. By name it simply validates, and no fingerprint is ever shown.

Uptime Kuma

Uptime Kuma answers the one question a hypervisor cannot: are the things you actually care about responding?

The app reads Uptime Kuma's Prometheus /metrics endpoint rather than its socket.io API. That endpoint is plain, documented, covers every monitor, and needs only an API key.

• The key is sent as an HTTP Basic password with an empty username, which is what Uptime Kuma expects. Nothing else needs configuring.
• There is nothing to start or stop here — a monitor is either answering or it isn't — so the app shows no controls for one.
• A monitor inside its retry window shows as degraded rather than down, so a single transient blip doesn't raise an alarm.
• A monitor in maintenance shows as paused and raises nothing. It was silenced deliberately.
• The app also warns when a TLS certificate is within 14 days of expiry — below Let's Encrypt's 30-day renewal, so it means renewal is genuinely broken rather than merely pending.

What the Uptime Kuma credential needs

Uptime Kuma answers the one question a hypervisor cannot: are the things you actually care about responding? The app reads its Prometheus `/metrics` endpoint rather than its socket.io API — that endpoint is plain, documented, covers every monitor, and needs only an API key.

Creating an API key

In Uptime Kuma: your profile (top right) → Settings → API Keys → Add API Key. The key is shown once.

Uptime Kuma → Settings → API Keys → Add API Key

• The key is used as an HTTP Basic password with an empty username, which is what Uptime Kuma expects. Nothing else needs configuring.
• There is nothing to start or stop here — a monitor is either answering or it isn't, so the app shows no controls for one.
• A monitor in Uptime Kuma's retry window shows as degraded rather than down, so a single transient blip doesn't raise an alarm.
• A monitor in maintenance shows as paused and raises nothing — it was silenced deliberately.
• If the server answers on HTTP but not HTTPS, set the connection to HTTP when adding it. Unraid serves its web UI on port 80 by default; Proxmox is HTTPS-only on 8006.
• Over HTTP your API token crosses the network unencrypted. That's a reasonable trade on a network you trust, and a bad one otherwise.
• Self-signed certificates are fine — the app shows you the fingerprint on first connect so you can compare it against the one the server's own web UI displays. After that a *changed* certificate is a hard failure until you approve it again.
• If the server has a real certificate — Let's Encrypt, or your own CA — add it by the name on that certificate rather than by its IP address. A certificate names hostnames, not addresses, so reaching it by IP fails the name check and drops you back to approving a fingerprint by hand — which you would then have to approve again at every renewal. By name it simply validates, and no fingerprint is ever shown.

Home Assistant

This integration is about the add-ons running inside Home Assistant — start, stop and restart them, and get told when one that is set to start on boot isn't running. That is the same check the app makes on a Proxmox guest, and it works the same way here.

It deliberately does not report entity counts, automation counts, or which entities are unavailable. A real install has hundreds of unavailable entities at any moment and almost all of them are expected — a number that is permanently alarming is a number people stop reading.

Entity states and availability were tried and removed: a battery sensor can read -1 while it works itself out, and hundreds of permanently unavailable entities is noise wearing the costume of a warning. Two entity checks survive, because they earn their place — a tripped smoke, leak or gas sensor, which is the one thing this app watches that is wrong in the physical world rather than in a computer, and a battery that has gone flat, because a dead sensor goes quiet rather than complaining.

• Add-ons need a Supervisor. Home Assistant OS and Supervised installs have one; Container and Core installs do not. The app distinguishes "this install has none" from "something went wrong" — only a 404 means the former, and anything else is reported with its reason.
• The token must belong to an administrator. Supervisor access is admin-only, so a limited user's token will read entities but show no add-ons.
• Add-ons are read over Home Assistant's WebSocket API. Recent releases refuse long-lived tokens on the older /api/hassio/ proxy — even an owner's token — so the app talks to the Supervisor the same way Home Assistant's own frontend does, and falls back to the proxy only on releases where it still works. Nothing to configure either way.
• Home Assistant listens on port 8123, over plain HTTP unless you have set up TLS.
• Stop and shut down both map to the Supervisor's single stop — it has no graceful/forced split, and pretending otherwise would be a lie about what the button does.
• Entities in the unknown state are never treated as broken. Plenty are legitimately unknown after a restart.

What the Home Assistant credential needs

This platform is about the **add-ons** running inside Home Assistant — start, stop and restart them, and be told when one set to start on boot isn't running. That is the same check the app makes on a Proxmox guest, and it works the same way here. It does not list your entities: a real install has hundreds that are unavailable at any moment and almost all of them are expected. Two entity checks survive because they earn it — a tripped smoke, leak or gas sensor, and a flat battery.

Creating a long-lived access token

In Home Assistant: click your user name (bottom left) → Security → Long-lived access tokens → Create token. It is shown once and never expires until revoked. Create it while signed in as an **administrator** — Supervisor access is admin-only, so a limited user's token reads entities and shows no add-ons at all.

Home Assistant → your user → Security → Long-lived access tokens

• The token carries that user's permissions. A token from an administrator can see everything; one from a limited user sees only what that user can.
• Add-ons need a Supervisor. Home Assistant OS and Supervised installs have one; Container and Core installs do not, and answer 404. That is a fact about the install rather than a failure, and is reported as a warning.
• The token must belong to an administrator. Supervisor access is admin-only, so a limited user's token connects, reads, and shows no add-ons — which looks like a broken server rather than a permission.
• Add-ons are read over Home Assistant's WebSocket API. Recent releases refuse long-lived tokens on the older /api/hassio/ proxy — even an owner's — so the app talks to the Supervisor the way the frontend does and falls back only where the proxy still works. Nothing to configure either way.
• Stop and shut down both map to the Supervisor's single stop. It has no graceful/forced split, and offering both would be a lie about what the button does.
• Home Assistant listens on port 8123 by default, over plain HTTP unless you've set up TLS.
• Entities in the `unknown` state are not treated as broken — plenty are legitimately unknown after a restart, and flagging those would mark a healthy install as faulty forever.
• A tripped smoke, leak or gas sensor is reported as critical. It is the one thing this app watches that is wrong in the physical world rather than in a computer.
• If the server answers on HTTP but not HTTPS, set the connection to HTTP when adding it. Unraid serves its web UI on port 80 by default; Proxmox is HTTPS-only on 8006.
• Over HTTP your API token crosses the network unencrypted. That's a reasonable trade on a network you trust, and a bad one otherwise.
• Self-signed certificates are fine — the app shows you the fingerprint on first connect so you can compare it against the one the server's own web UI displays. After that a *changed* certificate is a hard failure until you approve it again.
• If the server has a real certificate — Let's Encrypt, or your own CA — add it by the name on that certificate rather than by its IP address. A certificate names hostnames, not addresses, so reaching it by IP fails the name check and drops you back to approving a fingerprint by hand — which you would then have to approve again at every renewal. By name it simply validates, and no fingerprint is ever shown.

UniFi

The app uses UniFi's official Network Integration API, which needs Network 9.0 or newer. Older controllers only offer a session login with a username and password, which this app deliberately does not ask for.

• This is the Network application's key — not a UniFi account, and not a Site Manager cloud key.
• On a UDM or Cloud Key the app talks to /proxy/network/… automatically, so a standalone-controller URL is not needed.
• A device that is updating or being adopted shows as paused, not down. It is a transition you started, not a fault — otherwise pushing firmware to a fleet would set off alarms.
• Firmware updates are advisory. A UniFi fleet nearly always has one available, and treating that as a problem would leave the concerns card permanently full.
• Controllers use a self-signed certificate; the app shows the fingerprint on first connect so you can compare it.
• UniFi is read-only here. There is nothing to start or stop.

What the UniFi credential needs

The app uses UniFi's official Network Integration API, which needs Network 9.0 or newer. Older controllers only offer a session login with a username and password, which this app deliberately does not ask for. There is nothing to start or stop — a device is either reachable or it isn't — so UniFi is read-only here.

Creating an API key

In the UniFi Network application, open Integrations in the left-hand navigation and choose Create New API Key. The key is shown once. If there is no Integrations entry, this Network application is older than 9.0 — check Settings → System for its version, which is a different number from the console's firmware version and is usually lower.

UniFi Network → Integrations → Create New API Key

If your console puts it somewhere else

Where this lives has moved between releases and differs on a UniFi OS console. Only the Network application's own key works — a Site Manager cloud key is a different thing and is rejected.

UniFi OS console → Settings → Admins & Users → your admin → API Keys
Site Manager (unifi.ui.com) → a cloud key — NOT this

• This is the Network application's key, not a UniFi account or a Site Manager cloud key.
• If the app cannot connect, the error names which of the three things went wrong: a rejected key, a key with no site access, or no integration API on this controller at all.
• On a UDM or Cloud Key the app talks to /proxy/network/... — that is handled automatically, and is why a standalone-controller URL is not needed.
• A device that is updating or being adopted shows as paused rather than down. It is a transition somebody started, not a fault.
• Firmware updates are advisory. A UniFi fleet nearly always has one available, and treating that as a problem would leave the concerns card permanently full.
• Controllers use a self-signed certificate. The app shows the fingerprint on first connect so you can compare it.
• If the server answers on HTTP but not HTTPS, set the connection to HTTP when adding it. Unraid serves its web UI on port 80 by default; Proxmox is HTTPS-only on 8006.
• Over HTTP your API token crosses the network unencrypted. That's a reasonable trade on a network you trust, and a bad one otherwise.
• Self-signed certificates are fine — the app shows you the fingerprint on first connect so you can compare it against the one the server's own web UI displays. After that a *changed* certificate is a hard failure until you approve it again.
• If the server has a real certificate — Let's Encrypt, or your own CA — add it by the name on that certificate rather than by its IP address. A certificate names hostnames, not addresses, so reaching it by IP fails the name check and drops you back to approving a fingerprint by hand — which you would then have to approve again at every renewal. By name it simply validates, and no fingerprint is ever shown.

OPNsense

A firewall knows something nothing else in your homelab does: whether the internet is actually working. A WAN link that is down — or up and losing packets — leaves every server healthy and nothing usable.

pfSense is not supported. It ships no REST API in its base system; reaching one needs a third-party package that most installs don't have, with an entirely different shape. Saying so is better than claiming support that fails on a stock install.

Creating an API key and secret

In OPNsense: System → Access → Users → edit a user → API keys → +. A file downloads containing both halves; the secret is never shown again.

Prefer a dedicated user with only these privileges rather than issuing a key against an administrator:

Status: Gateways
Firmware
Diagnostics: System   (optional — memory use on the firewall)

• OPNsense sends both halves as HTTP Basic — the key is the username and the secret is the password. Entering only the key gives a 401 that looks like a wrong key rather than a missing half.
• A gateway with monitoring switched off shows as paused and raises nothing. That was a deliberate choice on the firewall.
• Packet loss is reported separately from a gateway being down, because a link losing packets is still carrying traffic. Everything works, badly — the hardest kind of fault to notice. The app warns at 5% and calls it critical at 20%; below 5% is ordinary internet weather.
• A pending reboot is treated as more serious than an available update: the firewall is running one version and configured for another.

What the OPNsense credential needs

A firewall knows something nothing else in your homelab does: whether the internet is actually working. A WAN link that is down — or up and losing packets — leaves every server healthy and nothing usable. **pfSense is not supported.** It ships no REST API in its base system; reaching one needs a third-party package most installs don't have.

Creating an API key and secret

In OPNsense: System → Access → Users → edit a user → API keys → +. A file downloads containing both halves; the secret is never shown again.

OPNsense → System → Access → Users → API keys

A read-only user for the app

Create a user with only the privileges above, rather than issuing a key against an administrator.

OPNsense → System → Access → Groups → add a group with:
  Status: Gateways
  Firmware
  Diagnostics: System   (optional)

• OPNsense sends both halves as HTTP Basic — the key is the username and the secret is the password. Entering only the key gives a 401 that looks like a wrong key rather than a missing half.
• A gateway with monitoring switched off shows as paused and raises nothing. That was a deliberate choice on the firewall.
• Packet loss is reported separately from a gateway being down, because a link losing packets is still carrying traffic — everything works, badly, which is the hardest kind of fault to notice.
• A pending reboot is treated as more serious than an available update: the firewall is running one version and configured for another.
• If the server answers on HTTP but not HTTPS, set the connection to HTTP when adding it. Unraid serves its web UI on port 80 by default; Proxmox is HTTPS-only on 8006.
• Over HTTP your API token crosses the network unencrypted. That's a reasonable trade on a network you trust, and a bad one otherwise.
• Self-signed certificates are fine — the app shows you the fingerprint on first connect so you can compare it against the one the server's own web UI displays. After that a *changed* certificate is a hard failure until you approve it again.
• If the server has a real certificate — Let's Encrypt, or your own CA — add it by the name on that certificate rather than by its IP address. A certificate names hostnames, not addresses, so reaching it by IP fails the name check and drops you back to approving a fingerprint by hand — which you would then have to approve again at every renewal. By name it simply validates, and no fingerprint is ever shown.

Pi-hole and AdGuard Home

DNS is the one service whose failure takes a whole house offline while every other reading stays green — the hypervisor is fine, the NAS is fine, and nothing resolves.

But the check worth having isn't uptime. It's whether filtering is still switched on. People disable it to load one page and forget, and nothing about that is visible afterwards: DNS keeps answering, no metric moves, and every ad and tracker is let through for weeks.

Pi-hole

Pi-hole 6 or newer. Version 6 replaced the API completely — the old /admin/api.php endpoint is gone rather than deprecated, so version 5 cannot be supported.

• Pi-hole limits how many API sessions can exist at once. The app keeps a single session, reuses it, and releases it when it stops — so it won't lock you out of your own admin interface.
• Blocking disabled with a timer raises nothing: it was deliberate and it will switch itself back on. Blocking disabled with no timer is a warning, because nothing will.
• Blocklists that haven't updated in a fortnight are flagged. pihole -g runs weekly by default, so that means the schedule has stopped rather than one run being missed.
• Blocking is a switch you can flip from the app, behind the same Face ID gate as everything else that changes a server. Turning it off asks first and says what it means; turning it back on doesn't, because that's a fix.
• Query counts are for the last 24 hours, and the graph covers the same window — total queries with blocked drawn underneath.

AdGuard Home

• AdGuard serves its interface on port 3000 by default, though many people move it to 80.
• Filtering being off is a warning rather than an error: DNS still resolves and nothing breaks, which is exactly why it goes unnoticed.
• Filtering on with every list disabled is caught separately — the same outcome by a different route, and even easier to miss.
• Enabled lists that haven't updated in a week are advisory. They keep working, just against last month's internet.

AdGuard Home is read-only in the app. Pi-hole's blocking switch is the one exception across both — it exists because seeing "blocking is disabled" and having no way to fix it names a problem and then hands it straight back.

What the Pi-hole credential needs

DNS is the one service whose failure takes the whole house offline while every other reading stays green. The check worth having, though, isn't uptime — it's whether blocking is still on. People disable it to load one page and forget, and nothing about that is visible afterwards. **Pi-hole 6 or newer.** Version 6 replaced the API completely; the old one is gone rather than deprecated.

Creating an app password

In Pi-hole: Settings → Web interface / API → Configure app password. Use this rather than your admin password — it can be revoked on its own.

Pi-hole → Settings → Web interface / API → Configure app password

• **Pi-hole limits how many API sessions can exist at once.** The app keeps one, reuses it, and releases it when it stops — so it won't lock you out of your own admin interface.
• Blocking disabled *with a timer* is treated as deliberate and raises nothing; it will switch itself back on. Blocking disabled with **no** timer is a warning, because nothing will ever turn it back on.
• Blocklists that haven't updated in a fortnight are flagged. `pihole -g` runs weekly by default, so that means the schedule has stopped rather than a run being missed.
• Blocking is the one thing the app can switch, behind the same biometric gate as every other change — showing "blocking is disabled" and offering no way to fix it would name a problem and hand it straight back. Turning it off asks first and says what it means; turning it back on does not, because that is a fix. Nothing else about Pi-hole can be changed from the app.
• Version 5 is not supported. Its API was removed in 6, and supporting an interface upstream has deleted would age badly.
• If the server answers on HTTP but not HTTPS, set the connection to HTTP when adding it. Unraid serves its web UI on port 80 by default; Proxmox is HTTPS-only on 8006.
• Over HTTP your API token crosses the network unencrypted. That's a reasonable trade on a network you trust, and a bad one otherwise.
• Self-signed certificates are fine — the app shows you the fingerprint on first connect so you can compare it against the one the server's own web UI displays. After that a *changed* certificate is a hard failure until you approve it again.
• If the server has a real certificate — Let's Encrypt, or your own CA — add it by the name on that certificate rather than by its IP address. A certificate names hostnames, not addresses, so reaching it by IP fails the name check and drops you back to approving a fingerprint by hand — which you would then have to approve again at every renewal. By name it simply validates, and no fingerprint is ever shown.

What the AdGuard Home credential needs

AdGuard Home's API *is* its web interface, so it uses the same username and password you sign in with. There is no separate key to create. As with Pi-hole, the check worth having isn't uptime — it's whether filtering is still switched on.

Which credentials to use

The ones you use to sign in to AdGuard Home. If you'd rather not reuse them, add a second user under Settings → General settings → Access.

AdGuard Home → Settings → General settings

• AdGuard serves its interface on port 3000 by default, though many people move it to 80. Set whichever you use.
• Filtering being off is a warning rather than an error: DNS still resolves and nothing breaks, which is exactly why it goes unnoticed for weeks.
• Filter lists enabled but not updating for a week are flagged as advisory — they keep working, just against last month's internet.
• The app can't change anything in AdGuard Home. It only reads.
• If the server answers on HTTP but not HTTPS, set the connection to HTTP when adding it. Unraid serves its web UI on port 80 by default; Proxmox is HTTPS-only on 8006.
• Over HTTP your API token crosses the network unencrypted. That's a reasonable trade on a network you trust, and a bad one otherwise.
• Self-signed certificates are fine — the app shows you the fingerprint on first connect so you can compare it against the one the server's own web UI displays. After that a *changed* certificate is a hard failure until you approve it again.
• If the server has a real certificate — Let's Encrypt, or your own CA — add it by the name on that certificate rather than by its IP address. A certificate names hostnames, not addresses, so reaching it by IP fails the name check and drops you back to approving a fingerprint by hand — which you would then have to approve again at every renewal. By name it simply validates, and no fingerprint is ever shown.

Troubleshooting

Every server shows as unreachable, and nothing else is wrong

Check 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.

"A TLS error caused the secure connection to fail"

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.

The server connects and says "online", but every number is blank

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 app refuses to connect after I reinstalled or upgraded the server

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.

A control action returns "missing privilege"

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.

An action reports "still running" instead of succeeding

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.

Face ID never prompts

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.

TrueNAS disks all read "Unknown"

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.

Refreshing is slow

A full refresh makes a lot of calls: on Proxmox, a version check plus one config lookup per stopped guest (cached between refreshes); on TrueNAS, alerts, reporting, temperatures and pool topology — though on releases with the JSON-RPC API those now share one websocket connection instead of paying a round trip each. On a large fleet it still adds up; reducing it further is known work in progress.

How the app decides something is wrong

And what it owes you once it has decided: every warning states the problem in plain words. Where the cause is configuration — a missing privilege, a token without a role — it carries the fix: why it happens, numbered steps, and the exact command, copyable. Where there is no fix, or the fix didn't help, a Diagnostics section holds the raw failure and an assembled report — app and platform versions, what was read, every warning — with a copy button and a one-tap email to support. The report never includes your credentials or your servers' addresses.

Stopped guests

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.

Advisory vs. attention

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.

Acknowledging a concern

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:

• Severity changed — a degraded pool became a failed one. The kind of problem is different now.
• It got measurably worse — the same problem, further along. The margin is measured from the moment you acknowledged, not from fixed boundaries: acknowledge a pool at 91% and you get quiet until 96%. Fixed tiers would let an acknowledgement at 94.9% fire again at 95.0%, which is exactly the nagging this exists to prevent.

Acknowledgements are per-server, and removing a server forgets them — so a re-added server doesn't arrive pre-silenced.

Thresholds

Every alert threshold is adjustable in Settings, and the defaults reproduce the app's behaviour exactly, so an untouched install is unchanged.

The agent (optional)

Everything above works with nothing but the phone. The agent is a small service you can run on your own hardware for the things a phone cannot do: keep polling while it is asleep, hold a year of history, and send notifications from hardware you own. It runs the app's own adapters, so it grades a problem exactly the way the phone does.

Installing it, pairing a phone with it, pairing again after a new or reset phone, and the certificate rules all have their own page: the agent.

Request a platform or feature

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.

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.

Contact

Email [email protected]. It's a small operation, so please include:

• The platform and its version — Proxmox 8.2, TrueNAS 25.10.6, Unraid 7.1.
• What you expected to see and what you saw instead.
• The exact wording of any error the app showed.

Never send an API token, a password, or a screenshot with one visible. Nothing about diagnosing a problem requires it.