Homepage Dashboard - TrueNAS WebSocket Support (fixes REST API deprecation warnings)

Apps and Virtualization
1

If you use the Homepage dashboard with TrueNAS SCALE 25.04 or newer, you may be seeing daily alerts about using deprecated REST API endpoints. The REST API will be completely removed in TrueNAS 26.04.

I created a fork that adds WebSocket JSON-RPC support to Homepage’s TrueNAS widget while keeping full backward compatibility with TrueNAS CORE.

What this fixes:

  • Eliminates REST API deprecation warnings on SCALE 25.04+

  • Future-proofs your setup for TrueNAS 26.04

  • Works with all existing TrueNAS widget features (alerts, pools, datasets, system info)

Installation is simple:

  1. Download 4 files from my fork

  2. Install the ws package (pnpm add ws)

  3. Add useWebsocket: true to your services.yaml

  4. Restart homepage

Tested on TrueNAS SCALE 25.10.1 with all endpoints working correctly.

GitHub Repository: https://github.com/Hackpig1974/homepage/tree/truenas-jsonrpc

Full installation instructions are in the README.

Backward Compatible: If you’re still on TrueNAS CORE or older SCALE versions, you don’t need to change anything. The widget continues to use REST API by default.

Let me know if you run into any issues or have questions!

2

This is great - thanks for doing this. I had logged an issue for this in the Homepage github. I looked at the code a little but it was beyond my abilities and time to make modifications myself. Shamoon replied that they are open to PR if some brave soul takes this on. Will you submit a PR to the project?
Thanks for being the brave soul :slight_smile:

1 Like
3

I did submit a Pull Request to the Homepage project. Unfortunately, because it was my first PR and I relied on AI assistance, it was flagged and rejected. As a result, my account was restricted from submitting further PRs or participating in discussions.

Until that access is reinstated, I’m not able to resubmit the work directly. Lesson learned on my end.

4

Thanks for all this, I had a few problems though, my fault I’m sure, so I asked Google Gemini to help me. The installation process that worked for me is described in the Google Doc: TrueNAS Homepage Dashboard Setup Guide - Google Docs

5

Just a heads up re the official Homepage docker image.

Following the Pull Request of @Damon1974 that got rejected for being too AI assisted a new PR was created by Shamoon of homepage maintenance team. Their PR allows for new websockets as well as old REST api. It is currently merged into dev/nightly builds and can be pulled with the :dev tag. It is expected to go into :latest tag at some time in next days/weeks.
It uses a similar approach and discussions and testing can be read by searching discussions and closed PR in the official homepage github repository.

Salient points noted so far:

  • It uses similar approach to “useWebsocket: true” but instead it uses a new line of “version: n” (1 = old REST api and 2 = websocket api).
    1 is the default if not supplied.

  • If websocket method is invoked with version: 2 and an API key is supplied then it forces secure wss:// connection (regardless of URL being http:// or https:// ). This means the API key does not get auto revoked by an insecure installation. You cannot use 127.0.0.1 if your homepage is polling remote server(s).

  • User / Password will work both with insecure http:// → ws:// or secure https:// → wss://

btw. using the original REST method with an API key seems the user needed to have a sign in. Most people probably using “truenas_admin” account with an API key added. With the new websocket connection a new user with no sign in and only RO admin access can be created and used instead. This new more secure user will only work with websockets authorisation.

Thanks to @Damon1974 for getting the ball rolling and providing the kickstart required.

1 Like
6

I’m currently locked out of that repo, but wanted to share some thoughts on potential next steps.

The current implementation works well, though there’s an opportunity to optimize connection management. Since each endpoint opens a new WebSocket connection per request, a typical refresh cycle (with all endpoints enabled) creates 4 full connection cycles every 5 seconds—roughly 17K connections daily.

Moving to a persistent connection model with connection pooling could significantly reduce this overhead while maintaining the same functionality. This was actually on my roadmap as a contribution.

I’d also been working on a more modular approach using a generic JSON-RPC WebSocket handler (jsonrpc-ws.js) that could be shared across widgets. The idea is that if other services (Proxmox, pfSense, etc.) add WebSocket support in the future, they could leverage the same base handler rather than duplicating the WebSocket logic. The TrueNAS-specific pieces would remain in the widget’s proxy handler as a thin routing layer.

Happy to collaborate on either of these improvements once access is restored, or I can share what I have built if it’s helpful. I appreciate the work getting WebSocket support merged as that solves a real pain point for TrueNAS 25.04 and higher users.

  • Damon1974
7

Yeah, that’s not ideal at all. It should probably be fixed.