From bad717f16eb7620dfd9c9f3f135be95f9a2f9642 Mon Sep 17 00:00:00 2001
From: rcourtman <8825017+rcourtman@users.noreply.github.com>
Date: Mon, 31 Aug 2026 06:41:11 +0100
Subject: [PATCH] Document agent URL updates when the server address changes

Restoring a configuration backup onto a Pulse instance with a new address
makes every agent vanish until each agent's configured --url (PULSE_URL for
containers) is updated, because agents dial the address they were installed
with. The post-migration checklist covered the token but not the address.

Refs #1813
---
 docs/MIGRATION.md                        | 5 +++++
 frontend-modern/public/docs/MIGRATION.md | 5 +++++
 2 files changed, 10 insertions(+)

diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md
index 3b88223f6..58de776f8 100644
--- a/docs/MIGRATION.md
+++ b/docs/MIGRATION.md
@@ -66,6 +66,11 @@ Because local login credentials are stored in `.env` (not part of exports), you
 3.  **Update Agents**:
     *   **Unified Agent**: Update the `--token` flag in your service definition.
     *   **Containerized agent**: Update `PULSE_TOKEN` in the agent container environment.
+    *   **New server address?** Agents dial the address they were installed
+        with (the `--url` flag, or `PULSE_URL` for containerized agents), so
+        agents disappear from the new instance until that value is updated in
+        each agent's service definition. Fronting Pulse with a DNS name
+        instead of an IP address makes future moves invisible to agents.
     *   *Tip: Use **Settings → Infrastructure → Install on a host** to generate updated install commands.*
 4.  **Relay/Pro/legacy Pro+/Cloud**: Re-activate your license key after migration (license files are not included in exports).
 
diff --git a/frontend-modern/public/docs/MIGRATION.md b/frontend-modern/public/docs/MIGRATION.md
index 3b88223f6..58de776f8 100644
--- a/frontend-modern/public/docs/MIGRATION.md
+++ b/frontend-modern/public/docs/MIGRATION.md
@@ -66,6 +66,11 @@ Because local login credentials are stored in `.env` (not part of exports), you
 3.  **Update Agents**:
     *   **Unified Agent**: Update the `--token` flag in your service definition.
     *   **Containerized agent**: Update `PULSE_TOKEN` in the agent container environment.
+    *   **New server address?** Agents dial the address they were installed
+        with (the `--url` flag, or `PULSE_URL` for containerized agents), so
+        agents disappear from the new instance until that value is updated in
+        each agent's service definition. Fronting Pulse with a DNS name
+        instead of an IP address makes future moves invisible to agents.
     *   *Tip: Use **Settings → Infrastructure → Install on a host** to generate updated install commands.*
 4.  **Relay/Pro/legacy Pro+/Cloud**: Re-activate your license key after migration (license files are not included in exports).