fivetran-paulharper · Nov 6, 2026
diff --git a/README.md b/README.md
@@ -70,7 +70,7 @@ Linux releases continue to use `proxy-agent:<version>` for backward compatibilit
 
 ### Installing behind a network proxy
 
-The installers and the `upgrade` command use a proxy for their web requests: downloading the management script, listing image tags, and fetching the agent configuration from Fivetran.
+The installers and the `upgrade` and `update-manager` commands use a proxy for their web requests: downloading the management script, listing image tags, and fetching the agent configuration from Fivetran.
 
 On Linux, the shell scripts use `curl`. Set `HTTPS_PROXY` or `https_proxy` for HTTPS URLs, which the scripts use by default. Set lowercase `http_proxy` for HTTP URLs; curl ignores uppercase `HTTP_PROXY`. `NO_PROXY` or `no_proxy` excludes hosts.
 
@@ -122,26 +122,92 @@ $HOME/fivetran-proxy-agent/
 Use `proxy-agent-manager.sh` to control the agent:
 
 ```bash
-./proxy-agent-manager.sh {start|stop|restart|upgrade|status|logs}
+./proxy-agent-manager.sh {start|stop|restart|upgrade|update-manager|status|logs}
 ```
 
 ### Windows
 
 Use `proxy-agent-manager.ps1` to control the agent:
 
 ```powershell
-& "$env:USERPROFILE\fivetran-proxy-agent\proxy-agent-manager.ps1" {start|stop|restart|upgrade|status|logs}
+& "$env:USERPROFILE\fivetran-proxy-agent\proxy-agent-manager.ps1" {start|stop|restart|upgrade|update-manager|status|logs}
 ```
 
 | Command   | Description                                          |
 |-----------|------------------------------------------------------|
 | `start`   | Start the agent container                            |
 | `stop`    | Stop and remove the agent container                  |
 | `restart` | Stop then start the agent container                  |
-| `upgrade` | Pull and start the latest version, with auto-rollback on failure |
+| `upgrade` | Pull and start the latest agent version, with auto-rollback on failure |
+| `update-manager` | Download and replace the management script without restarting the agent |
 | `status`  | Show container name, image, and health status        |
 | `logs`    | Stream live container logs                           |
 
+### Updating the management script
+
+Run `update-manager` as the user who installed the agent:
+
+```bash
+"$HOME/fivetran-proxy-agent/proxy-agent-manager.sh" update-manager
+```
+
+```powershell
+& "$env:USERPROFILE\fivetran-proxy-agent\proxy-agent-manager.ps1" update-manager
+```
+
+Use your installation directory if it differs from the default. This downloads the latest management script from this repository's `main` branch, checks that it is nonempty and has valid syntax, then replaces the installed script. A failed download or validation leaves the existing script intact. Configuration, settings, the pinned agent version, and the running container are unchanged; the new script takes effect on the next command. Updating the manager does not require Docker or valid agent configuration.
+
+`upgrade` updates only the agent container. To update both, run `update-manager` first, then invoke the script again with `upgrade`.
+
+#### Older installations without `update-manager`
+
+Replace the script manually once using the commands below. Set `agent_dir` or `$agentDir` to your installation directory if needed. These commands download to a temporary file and validate it before replacing the installed script; no agent restart is needed.
+
+Linux (Bash):
+
+```bash
+(
+    set -e
+    agent_dir="$HOME/fivetran-proxy-agent"
+    tmp_script=$(mktemp "$agent_dir/.proxy-agent-manager.XXXXXX")
+    trap 'rm -f "$tmp_script"' EXIT
+    curl -fSsL --max-time 30 \
+        https://raw.githubusercontent.com/fivetran/proxy_agent/main/proxy-agent-manager.sh \
+        -o "$tmp_script"
+    test -s "$tmp_script"
+    bash -n "$tmp_script"
+    chmod u+x "$tmp_script"
+    mv -f "$tmp_script" "$agent_dir/proxy-agent-manager.sh"
+)
+```
+
+Windows (PowerShell):
+
+```powershell
+& {
+    $ErrorActionPreference = 'Stop'
+    $agentDir = "$env:USERPROFILE\fivetran-proxy-agent"
+    $tmpScript = Join-Path $agentDir ('.proxy-agent-manager.' + [guid]::NewGuid() + '.ps1')
+    try {
+        Invoke-WebRequest -UseBasicParsing -TimeoutSec 30 `
+            -Uri https://raw.githubusercontent.com/fivetran/proxy_agent/main/proxy-agent-manager.ps1 `
+            -OutFile $tmpScript
+        if ([string]::IsNullOrWhiteSpace((Get-Content -LiteralPath $tmpScript -Raw))) {
+            throw 'Downloaded script is empty.'
+        }
+        $parseErrors = $null
+        $null = [System.Management.Automation.Language.Parser]::ParseFile($tmpScript, [ref]$null, [ref]$parseErrors)
+        if ($parseErrors.Count -gt 0) { throw 'Downloaded script has invalid syntax.' }
+        Unblock-File -LiteralPath $tmpScript
+        [System.IO.File]::Replace($tmpScript, (Join-Path $agentDir 'proxy-agent-manager.ps1'), [NullString]::Value)
+    } finally {
+        Remove-Item -LiteralPath $tmpScript -Force -ErrorAction SilentlyContinue
+    }
+}
+```
+
+The manual PowerShell download uses your system proxy settings; on Windows PowerShell 5.1, pass `-Proxy` and, if needed, `-ProxyUseDefaultCredentials` to `Invoke-WebRequest` when a proxy is required. The `update-manager` command itself uses the environment proxy settings described above.
+
 ## Troubleshooting
 
 ### Windows
@@ -183,7 +249,7 @@ The scripts read these environment variables so the tests can point them at the
 |----------|---------|----------|
 | `PROXY_AGENT_IMAGE` | management scripts | the agent image repository |
 | `PROXY_AGENT_REGISTRY_TAGS_URL` | installers and management scripts | the registry tag listing URL |
-| `PROXY_AGENT_SCRIPT_URL` | installers | the management script download URL |
+| `PROXY_AGENT_SCRIPT_URL` | installers and management scripts | the management script download URL |
 
 ## License
 

diff --git a/proxy-agent-manager.ps1 b/proxy-agent-manager.ps1
@@ -18,51 +18,11 @@ $SETTINGS_FILE = Join-Path $BASE_DIR 'settings.ps1'
 # Appended to the plain agent version to form the Linux image tag.
 $LINUX_IMAGE_TAG_SUFFIX = '-ubuntu-26.04'
 
-# settings.ps1 may set $MEMORY_ALLOCATION_MB and, for Windows containers,
-# $WINDOWS_VERSION (an LTSC variant that overrides host detection).
-if (Test-Path -LiteralPath $SETTINGS_FILE) {
-    . $SETTINGS_FILE
-}
-# Unset or empty only, so 0 is rejected like any other invalid setting.
-if ("$MEMORY_ALLOCATION_MB" -eq '') { $MEMORY_ALLOCATION_MB = 5120 }
-if (-not $WINDOWS_VERSION) { $WINDOWS_VERSION = $null }
-
 # ── Startup validation ───────────────────────────────────────────────────────
 
-$validCommands = @('start', 'stop', 'restart', 'upgrade', 'status', 'logs')
+$validCommands = @('start', 'stop', 'restart', 'upgrade', 'update-manager', 'status', 'logs')
 if (-not $Command -or $Command -notin $validCommands) {
-    Write-Host "Usage: $($MyInvocation.MyCommand.Name) {start|stop|restart|upgrade|status|logs}"
-    exit 1
-}
-
-if (-not (Test-Path $CONFIG_FILE)) {
-    Write-Host "ERROR: Config file not found: $CONFIG_FILE" -ForegroundColor Red
-    exit 1
-}
-
-try {
-    $configJson = Get-Content $CONFIG_FILE -Raw | ConvertFrom-Json
-} catch {
-    Write-Host "ERROR: Failed to parse config file: $_" -ForegroundColor Red
-    exit 1
-}
-
-$AGENT_ID = $configJson.agent_id
-if (-not $AGENT_ID -or $AGENT_ID -eq 'null') {
-    Write-Host "ERROR: 'agent_id' missing in $CONFIG_FILE" -ForegroundColor Red
-    exit 1
-}
-
-$CONTAINER_NAME = "proxy-agent-$AGENT_ID"
-
-if (-not (Test-Path $VERSION_FILE)) {
-    Write-Host "ERROR: $VERSION_FILE not found." -ForegroundColor Red
-    exit 1
-}
-
-$PINNED_VERSION = (Get-Content $VERSION_FILE -Raw).Trim()
-if (-not $PINNED_VERSION) {
-    Write-Host "ERROR: $VERSION_FILE is empty." -ForegroundColor Red
+    Write-Host "Usage: $($MyInvocation.MyCommand.Name) {start|stop|restart|upgrade|update-manager|status|logs}"
     exit 1
 }
 
@@ -143,6 +103,34 @@ function Set-WebProxyFromEnvironment {
     Write-Log "Using proxy $proxyAddress from the environment"
 }
 
+# Validate the download before atomically replacing the installed script.
+function Update-Manager {
+    $scriptUrl = if ($env:PROXY_AGENT_SCRIPT_URL) { $env:PROXY_AGENT_SCRIPT_URL } else { 'https://raw.githubusercontent.com/fivetran/proxy_agent/main/proxy-agent-manager.ps1' }
+    $tmpScript = Join-Path $BASE_DIR ('.proxy-agent-manager.' + [guid]::NewGuid() + '.ps1')
+    try {
+        Set-WebProxyFromEnvironment -ProbeUri ([Uri]$scriptUrl)
+        Write-Host "Downloading management script..."
+        Invoke-WebRequest -Uri $scriptUrl -OutFile $tmpScript -UseBasicParsing -TimeoutSec 30
+        if ([string]::IsNullOrWhiteSpace((Get-Content -LiteralPath $tmpScript -Raw))) {
+            throw 'Downloaded management script is empty.'
+        }
+        $parseErrors = $null
+        $null = [System.Management.Automation.Language.Parser]::ParseFile($tmpScript, [ref]$null, [ref]$parseErrors)
+        if ($parseErrors.Count -gt 0) {
+            throw 'Downloaded management script has invalid syntax.'
+        }
+        Unblock-File -LiteralPath $tmpScript
+        # $null binds to an empty string here; Replace requires a null backup path.
+        [System.IO.File]::Replace($tmpScript, $PSCommandPath, [NullString]::Value)
+        Write-Host "Management script updated. The agent has not been restarted."
+    } catch {
+        Write-Host "ERROR: Failed to update management script: $_" -ForegroundColor Red
+        exit 1
+    } finally {
+        Remove-Item -LiteralPath $tmpScript -Force -ErrorAction SilentlyContinue
+    }
+}
+
 function Get-ContainerOsType {
     $osTypeOutput = docker info --format '{{.OSType}}' 2>$null
     if ($LASTEXITCODE -ne 0) {
@@ -463,6 +451,52 @@ function Invoke-Upgrade {
 
 # ── Commands ─────────────────────────────────────────────────────────────────
 
+# Updating the manager does not require agent configuration or Docker.
+if ($Command -eq 'update-manager') {
+    Update-Manager
+    exit 0
+}
+
+# settings.ps1 may set $MEMORY_ALLOCATION_MB and, for Windows containers,
+# $WINDOWS_VERSION (an LTSC variant that overrides host detection).
+if (Test-Path -LiteralPath $SETTINGS_FILE) {
+    . $SETTINGS_FILE
+}
+# Unset or empty only, so 0 is rejected like any other invalid setting.
+if ("$MEMORY_ALLOCATION_MB" -eq '') { $MEMORY_ALLOCATION_MB = 5120 }
+if (-not $WINDOWS_VERSION) { $WINDOWS_VERSION = $null }
+
+if (-not (Test-Path $CONFIG_FILE)) {
+    Write-Host "ERROR: Config file not found: $CONFIG_FILE" -ForegroundColor Red
+    exit 1
+}
+
+try {
+    $configJson = Get-Content $CONFIG_FILE -Raw | ConvertFrom-Json
+} catch {
+    Write-Host "ERROR: Failed to parse config file: $_" -ForegroundColor Red
+    exit 1
+}
+
+$AGENT_ID = $configJson.agent_id
+if (-not $AGENT_ID -or $AGENT_ID -eq 'null') {
+    Write-Host "ERROR: 'agent_id' missing in $CONFIG_FILE" -ForegroundColor Red
+    exit 1
+}
+
+$CONTAINER_NAME = "proxy-agent-$AGENT_ID"
+
+if (-not (Test-Path $VERSION_FILE)) {
+    Write-Host "ERROR: $VERSION_FILE not found." -ForegroundColor Red
+    exit 1
+}
+
+$PINNED_VERSION = (Get-Content $VERSION_FILE -Raw).Trim()
+if (-not $PINNED_VERSION) {
+    Write-Host "ERROR: $VERSION_FILE is empty." -ForegroundColor Red
+    exit 1
+}
+
 switch ($Command) {
     'start' {
         $CURRENT_VERSION = Get-ReleaseVersion -Tag $PINNED_VERSION

diff --git a/proxy-agent-manager.sh b/proxy-agent-manager.sh
@@ -2,7 +2,7 @@
 #
 #  Management script for Fivetran Proxy Agent (Docker)
 #
-#  Usage: ./proxy-agent-manager.sh {start|stop|restart|upgrade|status|logs}
+#  Usage: ./proxy-agent-manager.sh {start|stop|restart|upgrade|update-manager|status|logs}
 #
 set -euo pipefail
 
@@ -23,30 +23,6 @@ get_agent_id() {
         || true
 }
 
-if [ ! -f "$CONFIG_FILE" ]; then
-    echo "ERROR: Config file not found: $CONFIG_FILE"
-    exit 1
-fi
-
-AGENT_ID=$(get_agent_id)
-if [ -z "$AGENT_ID" ] || [ "$AGENT_ID" = "null" ]; then
-    echo "ERROR: 'agent_id' missing in $CONFIG_FILE"
-    exit 1
-fi
-
-CONTAINER_NAME="proxy-agent-${AGENT_ID}"
-
-if [ ! -f "$VERSION_FILE" ]; then
-    echo "ERROR: $VERSION_FILE not found."
-    exit 1
-fi
-# Also strips the UTF-8 byte order mark an editor on Windows may add.
-PINNED_VERSION=$(LC_ALL=C tr -d '[:space:]\357\273\277' < "$VERSION_FILE")
-if [ -z "$PINNED_VERSION" ]; then
-    echo "ERROR: $VERSION_FILE is empty."
-    exit 1
-fi
-
 LOGFILE="$BASE_DIR/logs/proxy-agent-manager.log"
 CONTAINER_LOG_DIR="/app/logs"
 
@@ -58,12 +34,6 @@ log() {
     echo "$(date -u +'%Y-%m-%d %H:%M:%S') UTC - $1" >> "$LOGFILE"
 }
 
-if [ -f "$SETTINGS_FILE" ]; then
-    # shellcheck disable=SC1090
-    source "$SETTINGS_FILE"
-fi
-MEMORY_ALLOCATION_MB="${MEMORY_ALLOCATION_MB:-5120}"
-
 # Only the commands that start a container check the setting, so stop, status
 # and logs still work with an invalid one.
 check_memory_allocation() {
@@ -73,6 +43,28 @@ check_memory_allocation() {
     fi
 }
 
+# Download beside the installed script so rename replaces it atomically.
+# The subshell confines the cleanup trap to this command.
+update_manager() (
+    local script_url="${PROXY_AGENT_SCRIPT_URL:-https://raw.githubusercontent.com/fivetran/proxy_agent/main/proxy-agent-manager.sh}"
+    local tmp_script
+    tmp_script=$(mktemp "$BASE_DIR/.proxy-agent-manager.XXXXXX")
+    trap 'rm -f "$tmp_script"' EXIT
+
+    echo "Downloading management script..."
+    if ! curl -fSsL --max-time 30 "$script_url" -o "$tmp_script"; then
+        echo "ERROR: Failed to download management script" >&2
+        exit 1
+    fi
+    if [ ! -s "$tmp_script" ] || ! bash -n "$tmp_script"; then
+        echo "ERROR: Downloaded management script is empty or has invalid syntax" >&2
+        exit 1
+    fi
+    chmod u+x "$tmp_script"
+    mv -f "$tmp_script" "$0"
+    echo "Management script updated. The agent has not been restarted."
+)
+
 get_latest_version() {
     local registry_host="${IMAGE%%/*}"
     local repository_path="${IMAGE#*/}"
@@ -201,6 +193,43 @@ start_agent() {
 
 # ── Commands ─────────────────────────────────────────────────────────────────
 
+# Updating the manager does not require agent configuration or Docker. Exit in
+# this parsed block so Bash never resumes reading the replaced script.
+if [ "${1:-}" = "update-manager" ]; then
+    update_manager
+    exit 0
+fi
+
+if [ ! -f "$CONFIG_FILE" ]; then
+    echo "ERROR: Config file not found: $CONFIG_FILE"
+    exit 1
+fi
+
+AGENT_ID=$(get_agent_id)
+if [ -z "$AGENT_ID" ] || [ "$AGENT_ID" = "null" ]; then
+    echo "ERROR: 'agent_id' missing in $CONFIG_FILE"
+    exit 1
+fi
+
+CONTAINER_NAME="proxy-agent-${AGENT_ID}"
+
+if [ ! -f "$VERSION_FILE" ]; then
+    echo "ERROR: $VERSION_FILE not found."
+    exit 1
+fi
+# Also strips the UTF-8 byte order mark an editor on Windows may add.
+PINNED_VERSION=$(LC_ALL=C tr -d '[:space:]\357\273\277' < "$VERSION_FILE")
+if [ -z "$PINNED_VERSION" ]; then
+    echo "ERROR: $VERSION_FILE is empty."
+    exit 1
+fi
+
+if [ -f "$SETTINGS_FILE" ]; then
+    # shellcheck disable=SC1090
+    source "$SETTINGS_FILE"
+fi
+MEMORY_ALLOCATION_MB="${MEMORY_ALLOCATION_MB:-5120}"
+
 case "${1:-}" in
     start)
         CURRENT_VERSION=$(get_release_version "$PINNED_VERSION") || exit 1
@@ -238,7 +267,7 @@ case "${1:-}" in
         ;;
 
     *)
-        echo "Usage: $0 {start|stop|restart|upgrade|status|logs}"
+        echo "Usage: $0 {start|stop|restart|upgrade|update-manager|status|logs}"
         exit 1
         ;;
 esac