Safe Updates, Backups & Rollback

A successful update means more than a window opening. Your profiles, local rules and required network workflows should still work, with a defined recovery path if they do not. Use this sequence: capture a baseline, preserve a readable snapshot, install the matching build, test essential workflows, then accept the new version.

This is a maintenance method for Windows, macOS and Linux desktops, not a promise that arbitrary versions support direct downgrades. Release-specific migration instructions take precedence. For managed computers or remote hosts, agree on a maintenance window and avoid experimenting over your only remote connection.

1. Separate three things you may need to restore

  • Software and runtime: installer, client version, core version and relevant runtime components. Keeping an old installer does not save your settings.
  • User data: subscription records, local profiles, overrides or scripts, custom rules and application preferences. Downloading a subscription again may not recover local changes.
  • System state: system proxy, TUN or service mode, DNS, startup behavior and permissions. An application export may not contain these settings.

A YAML file is not necessarily a complete recovery plan. List the workflows you actually depend on, then identify the data and settings behind them. There is no need to enable unused features merely to test an upgrade.

2. Complete five preflight checks

  1. Record the working client and core versions, OS version and processor architecture.
  2. Run your essential workflow once: profile loading, expected rule matching and access from the relevant application.
  3. Read the target release notes for requirements, known issues, migrations and security fixes.
  4. Confirm your installation channel. For package-managed installations, understand its update, version-retention and downgrade process before mixing channels.
  5. Prepare a usable backup and a trusted recovery installer; choose a time that will not disrupt important work.

Distinguish Windows x64 from ARM64, macOS Apple Silicon from Intel, and Linux package format from processor architecture. A filename containing “64” is not sufficient identification. Check current platform requirements in the project installation guide and this site's download pages.

3. Create an offline snapshot you can actually read

Locate the active data directory through your version's settings or documentation. If the interface offers an open-configuration-directory action, use it. Do not borrow a fixed path from a different installation method or mistake the program directory for user data.

  1. Record the directory and settings required for recovery. If using an export feature, establish what it includes.
  2. Exit normally and ensure the relevant configuration is no longer being written before copying it to a separate dated location. Do not forcibly stop unrelated services.
  3. Open several important files in the copy. Check its structure, file inventory and custom rules. For an archive or encrypted container, verify that it can be unlocked and read.
  4. Keep recovery instructions and version information with the snapshot, without placing subscription URLs or passwords in public notes.

Backups may contain node credentials, subscription tokens, controller secrets or synchronization credentials. Restrict access and use trusted encrypted storage. Do not upload them to a public repository, forum or cloud location with unverified protections. Seeing filenames alone does not demonstrate recoverability.

4. Verify the package instead of bypassing warnings

Obtain the release from the project or a trusted management channel. Check the publisher, version, architecture, format and size. Compare against an official checksum or verifiable signature when supplied. A hash you compute yourself identifies your copy; it does not independently establish a trustworthy source.

For Windows runtime problems, consult the project FAQ. For macOS security warnings, establish provenance and consult the platform guidance rather than disabling system checks. On Linux, use the appropriate package-management process for dependencies. Do not run an unexplained “one-click repair” script.

5. Run the same acceptance checklist after installation

Keep the original backup intact. Avoid simultaneously refreshing every subscription and rewriting rules. Confirm that the running version is the intended build rather than another installation reached through an old shortcut.

  1. Startup and data: the application opens, required profiles and overrides remain present, and logs show no persistent loading or parsing failures.
  2. Rules: test one destination intended to go direct and another intended to use your configured proxy; inspect the actual matching records.
  3. Applications: repeat the original everyday workflow, not just an internal latency test.
  4. Required modes: verify only System Proxy, TUN or service functions you already need, including permissions and logs.
  5. Lifecycle: close and reopen the client, then test again. During the maintenance window, check reconnect or sleep/wake behavior.
  6. Exit behavior: exit normally and verify expected proxy settings, avoiding a leftover reference to a stopped listener.

Write down outcomes rather than a single “update successful” note. Treat the new version as your stable baseline after the browser, required application and reconnect tests pass.

6. Decide whether a rollback is justified

If only one remote service fails, compare other destinations and network conditions. Timing alone does not prove a regression. A repeatable startup failure, persistent configuration parse error or essential workflow failure under the same profile and environment gives a stronger reason to assess rollback.

Preserve redacted logs and a current data copy first. If the older version has a known security issue, do not stay on it indefinitely for convenience; seek a fixed release or a supported temporary workflow that avoids the defect.

7. Roll back without mixing incompatible state

  1. Stop making further changes and record the failure and rollback reason.
  2. Exit normally and preserve post-update data so new work is not lost.
  3. Check release notes and channel support for downgrade limitations. An older program may not understand migrated data.
  4. Use a trusted older installer or the relevant package-manager process. Restore the matching pre-update snapshot only through a supported recovery procedure.
  5. Repeat the same acceptance checklist to demonstrate recovery rather than merely a successful launch.

Do not layer old and new directories indiscriminately or delete all data before trying recovery. Without a pre-update snapshot, lossless rollback cannot be promised. Preserve everything, seek project support and, when appropriate, test a minimal configuration in a supported isolated environment.

8. Keep a maintenance record without secrets

Time and time zone:
Previous / target / core versions:
OS / architecture / installation channel:
Backup location and read verification:
Baseline and post-update results:
Rollback decision / reason / recovery result:

Hypothetical example: subscriptions still update, but local rules disappear. Downloading the subscription again does not prove those rules will return. Inspect the old profile, overrides and export coverage before restoring. Back up the working environment, not just whichever file is easiest to find.

Retain at least one verified readable old snapshot until the new baseline has passed your important workflows. Apply practical retention and privacy requirements when cleaning up; a backup must not become a public configuration archive.

Related guides

References

References checked: 2026-10-14. Links below are project and platform documentation. This is an independently edited guide.

Updates,Backups,Rollback,Maintenance