Updated Updated: September 16, 2026

TrueNAS API Migration Project Plan#

TrueNAS is warning that one or more tools connected to it are still using an older communication method that will stop working in a future TrueNAS upgrade. The solution is to identify every tool using that method—including the AI agent, Home Assistant, Homepage, and any other integrations—move each one to the supported communication method, and test them one at a time before upgrading the servers. This project changes how the tools talk to TrueNAS; it does not change storage, datasets, backups, or other data. The AI agent is a likely source of the warning, but it must be confirmed rather than assumed to be the only source.

Older communication method — REST API

The tool sends separate requests to TrueNAS using ordinary web addresses, similar to visiting a website. TrueNAS is retiring this older method, so tools that still use it will eventually stop working.

New communication method — JSON-RPC over WebSocket

The tool opens a secure, ongoing conversation with TrueNAS and sends requests through it. It can perform the same kinds of tasks, but uses the newer method that TrueNAS supports for future releases.

What to expect

We should be able to migrate the existing functions. TrueNAS is changing the way tools communicate with it, not removing the underlying capabilities such as pools, datasets, alerts, shares, apps, and monitoring. The current MCP package may need to be replaced or adapted because it appears to use the old method. Home Assistant and Homepage must be checked separately. A few specialised functions may need redesign, but we do not expect all API-based functionality to disappear. We will test the replacement on one low-risk server before changing the rest.

https://api.truenas.com/v25.10/jsonrpc.html

1. Goal#

1.1 Definition of success#

The project is complete when every affected tool has been moved to the supported connection method, its required functions still work, and the REST warning no longer returns.

1.1.1 Scope boundary#

  • 1.1.1.1 Do not change storage pools, datasets, backups, replication, or network settings as part of this project.

2. Current Understanding#

2.1 Evidence already available#

  • 2.1.1 The warning identifies 10.1.2.4, documented as the Mac Studio.
  • 2.1.2 The ai-agent API key is used for MCP connections.
  • 2.1.3 Home Assistant and homepage have separate active API keys and must be checked independently.
  • 2.1.4 The unas_backup API key is revoked and should not be used.
  • 2.1.5 The public truenas-mcp-server package appears to use the older REST method.

The client responsible for each warning still needs to be confirmed. Being an MCP client does not by itself prove that MCP caused the warning.

3. Inventory#

3.1 TrueNAS servers#

  • 3.1.1 Make a list of every affected TrueNAS server, its address, and its current software version.
  • 3.1.2 Mark each server as pilot, production, or not currently in use.
  • 3.1.3 Choose one low-risk server for the first test.

3.2 Connected tools#

  • 3.2.1 Make one list containing MCP, Home Assistant, Homepage, monitoring, automation, and any other TrueNAS clients.
  • 3.2.2 For each client, record its source computer, target server, API-key name, and whether it uses the old or new method.
  • 3.2.3 Check the Mac Studio and relevant application settings for any other direct TrueNAS connections.

4. Choose the Replacement#

4.1 MCP#

  • 4.1.1 Choose whether to replace the current MCP package or adapt it to use the supported TrueNAS connection method.
  • 4.1.2 Keep the existing MCP names and functions wherever practical.

4.2 Other tools#

  • 4.2.1 Check whether Home Assistant supports the new method or needs a different integration.
  • 4.2.2 Check whether Homepage supports the new method or needs a different integration.
  • 4.2.3 Decide what to do with any other client that still depends on REST.

4.3 Safety standards#

  • 4.3.1 Use secure connections and keep API keys in 1Password; do not place keys in this vault.
  • 4.3.2 Use the least access each client needs.
  • 4.3.3 Do not revoke or replace existing keys until the replacement has been tested successfully.

5. Pilot Migration#

5.1 Prepare#

  • 5.1.1 Save the current client configuration so it can be restored if needed.
  • 5.1.2 Record what currently works on the pilot server.
  • 5.1.3 Confirm the pilot API key and connection details without recording the secret value.

5.2 Migrate one client#

5.2.1 First test#

  • 5.2.1.1 Migrate the MCP connection for one low-risk TrueNAS server.
  • 5.2.1.2 Test basic read-only functions such as server status, pools, datasets, alerts, and shares.
  • 5.2.1.3 Confirm the AI client can still start and use the MCP server.

5.3 Pilot decision#

  • 5.3.1 Watch the pilot for at least 24 hours.
  • 5.3.2 Continue only if the functions work and no new REST warning appears.
  • 5.3.3 Restore the previous configuration and investigate if the pilot fails.

6. Fleet Migration#

6.1 Migrate the remaining clients#

  • 6.1.1 Migrate the remaining MCP connections one server at a time.
  • 6.1.2 Migrate Home Assistant separately if it is confirmed to use REST.
  • 6.1.3 Migrate Homepage separately if it is confirmed to use REST.
  • 6.1.4 Migrate or replace any other affected clients found during the inventory.

6.2 Check each change#

  • 6.2.1 Test the affected client immediately after each migration.
  • 6.2.2 Stop the rollout if a client stops working, a REST warning appears, or an unexpected change occurs.
  • 6.2.3 Record which server and client were completed.

7. Clean-up and Verification#

7.1 Remove the old path#

  • 7.1.1 Remove old REST package or configuration references only after the replacement works.
  • 7.1.2 Confirm that no client still depends on the old path.
  • 7.1.3 Keep the old configuration available until the rollout is stable.
  • 7.1.4 Revoke obsolete API keys only after the rollback period has ended.

7.2 Confirm the result#

  • 7.2.1 Confirm all required clients are working.
  • 7.2.2 Confirm backups, replication, notifications, and storage operations were not affected.
  • 7.2.3 Monitor the TrueNAS alerts for seven days with no repeated REST warning.
  • 7.2.4 Confirm every affected server is ready for a future TrueNAS 26 upgrade.

8. Documentation and Closeout#

8.1 Update the Homelab notes#

  • 8.1.1 Record the final client, server, connection method, and API-key name for each integration.
  • 8.1.2 Update the MCP Configuration Guide with the final setup.
  • 8.1.3 Record any client that could not be migrated and its workaround.

8.2 Finish the project#

  • 8.2.1 Confirm all tasks in Sections 3 through 7 are complete.
  • 8.2.2 Record the date of the last REST warning.
  • 8.2.3 Mark this plan complete only after seven days without recurrence.

9. References#

9.1 Homelab notes#

9.2 TrueNAS references#

Backward Home Assistant - Alarmo Presence Disarm Scripts Management Process Forward