Agent self-update

The MigrationFox Windows agent checks for a new version on every poll interval and upgrades itself in-place between jobs. You install it once and never think about it again.

How it works

The agent polls the MigrationFox API on a configurable interval (default 15 seconds) for queued jobs. On every poll, the response includes the current recommended agent version as a version string (e.g. 2.1.2). If the agent is running an older version:

1. The agent downloads the new binary over HTTPS to a _staging\ subdirectory under its install folder.
2. The agent verifies the Authenticode signature. If the signature does not match the MigrationFox code-signing certificate, the update is aborted.
3. The agent writes a tiny launcher that will: (a) wait for the current process to exit, (b) move the staged binary over the running binary, (c) start the new process.
4. The agent exits. The launcher runs. The new version takes over and resumes polling on the same configuration.

If there is an active job, the update waits. An in-flight migration is never interrupted to install a new agent — the agent completes the current job (or batch of files it has claimed), then performs the swap, then resumes polling.

Version display

The current version is always visible in two places:

• The install dialog shows the version on the splash and in the success confirmation.
• The agent icon tooltip (system tray, when running with UI) shows MigrationFox Agent 2.1.2.

For scripted deployments, run agent.exe --version to print the version string and exit.

Controlling the update channel

By default the agent tracks the stable channel. Set the channel in the agent config file at C:\ProgramData\MigrationFox\agent.toml:

# agent.toml
[update]
channel = "stable"      # or "beta" for preview builds
check_interval = "15s"  # how often to ping the update endpoint
auto_apply = true       # set false to disable auto-update

With auto_apply = false the agent logs the availability of a new version but does not install it. Upgrade manually by downloading the new installer from the admin console.

Safety

• Authenticode signature verification is enforced on every downloaded binary. An unsigned or wrongly-signed update is rejected and logged as a security event.
• In-flight jobs are never interrupted. Any claimed files finish transferring before the swap.
• Downgrade protection — the agent will not downgrade itself. If the API advertises an older version, the agent logs a warning and ignores it.
• Rollback — the previous binary is retained in _staging\previous\ until the next update cycle. If a new version misbehaves, manually swap back and file a bug.

Troubleshooting

The agent is not updating

Check the log at C:\ProgramData\MigrationFox\agent.log for update check entries. If you see update check skipped · auto_apply=false, enable auto_apply in the config. If you see download failed, verify outbound HTTPS to agent-updates.migrationfox.com on port 443.

Signature verification is failing

Confirm Windows trusts the MigrationFox code-signing root. Some group policies strip certificate chains — a certmgr export of the root is available from support.

The agent crashes on first start after update

Restore the previous binary from _staging\previous\ and report the issue with the log file attached. The agent will keep running on the previous version until the next update cycle.

Related

• Agent troubleshooting — install, connectivity, permissions
• Junk file auto-skip — what the agent filters by default
• Google Drive migration reliability — how the agent handles source throttling