Migration Guide from Clash Verge Original to Clash Verge Rev: Complete Step-by-Step Tutorial

Uninstall the original Clash Verge, install the Tauri 2-based Clash Verge Rev, then manually copy your profiles and configuration files from ~/.config/clash-verge to the new ~/.config/clash-verge-rev directory.

Clash Verge Rev represents a complete architectural rewrite of the original Clash Verge project, migrating from an Electron-based stack to the Tauri 2 framework with a Rust-centric backend. This migration guide from Clash Verge original to Clash Verge Rev addresses the breaking changes in configuration storage, service architecture, and core engine integration that require manual intervention when upgrading.

Why Migration Is Necessary

The shift to Clash Verge Rev introduces several breaking changes that prevent automatic configuration inheritance. The application now ships with the Clash.Meta (mihomo) core internally and reorganizes its configuration layout between src-tauri/ (Rust backend) and src/ (React/TypeScript frontend).

Area	Original Clash Verge	Clash Verge Rev	Migration Impact
Service Mode	Privileged system daemon	Service or sidecar (user-space) modes with auto-installation	Old service files are incompatible; new installer uses different configuration locations
Configuration Directory	Fixed ~/.config/clash-verge	Portable .config in app bundle or new default path	Old configs not auto-loaded; manual copy required
TUN Stack	Legacy mixed stack	Defaults to gVisor with auto-migration path	Existing TUN settings may be ignored unless updated
Extensions	Plain YAML with prepend/append	"扩展配置" and "扩展脚本" with new priority order	Extension files must be relocated or recreated
Release Channels	No channel handling	Stable / Alpha (EOL) / AutoBuild channels	Users must select appropriate channel when reinstalling

According to the official changelog in docs/Changelog.history.md, the developers explicitly warn: "建议卸载旧版本后再安装新版本，该版本安装后不会使用旧版配置文件，你可以手动将旧版配置文件迁移到新版配置文件目录下" (It is recommended to uninstall the old version before installing the new version; this version will not use the old configuration files after installation, and you can manually migrate the old configuration files to the new configuration directory).

Pre-Migration Checklist

Before beginning the migration from Clash Verge to Clash Verge Rev, complete these preparatory steps to prevent data loss.

1. Export your active profile from the original application to ensure you have a backup of your proxy configurations.
2. Document your TUN settings if you use the TUN mode, as these require manual reconfiguration in the new version.
3. Note your service mode preference (system service vs. user mode) to replicate it during the new installation.
4. Back up the entire configuration directory using the command:

   cp -r ~/.config/clash-verge ~/.config/clash-verge-backup-$(date +%Y%m%d)

Step-by-Step Migration Process

1. Backup Original Configuration

Preserve your existing setup before uninstalling. The original application stores configurations in ~/.config/clash-verge on Linux/macOS and %APPDATA%\clash-verge on Windows.

# Linux/macOS

cp -r ~/.config/clash-verge ~/.config/clash-verge-backup

# Windows (PowerShell)

Copy-Item -Path "$env:APPDATA\clash-verge" -Destination "$env:APPDATA\clash-verge-backup" -Recurse

2. Uninstall Original Clash Verge

Remove the legacy application completely to prevent conflicts with the new service architecture.

• Windows: Uninstall via "Add or Remove Programs" in Settings.

• macOS: Drag the application to Trash and remove service files:

  sudo rm -rf /usr/local/lib/clash-verge
  sudo rm /Library/LaunchDaemons/com.clash-verge.service.plist

• Linux: Remove the binary and systemd service:

  sudo systemctl disable clash-verge
  sudo rm /etc/systemd/system/clash-verge.service

3. Install Clash Verge Rev

Download the appropriate installer from the clash-verge-rev/clash-verge-rev releases page. The project offers three channels:

• Stable: Recommended for most users.
• AutoBuild: Nightly builds with latest features.
• Alpha (EOL): Legacy channel, not recommended for new installations.

The installer automatically creates the new configuration directory at ~/.config/clash-verge-rev (or a portable .config folder if using the portable version).

4. Migrate Configuration Files

Copy your backed-up configuration to the new location. The new architecture stores profiles and settings in specific locations referenced by src-tauri/src/config/profiles.rs and loaded via src/services/preload.ts.

# Copy main configuration files

cp ~/.config/clash-verge-backup/profiles.yaml ~/.config/clash-verge-rev/
cp ~/.config/clash-verge-backup/config.yaml ~/.config/clash-verge-rev/

# Copy extension directories (merge and script configurations)

cp -r ~/.config/clash-verge-backup/merge ~/.config/clash-verge-rev/
cp -r ~/.config/clash-verge-backup/script ~/.config/clash-verge-rev/

5. Update TUN and Service Settings

Launch Clash Verge Rev and verify your TUN settings. The application now defaults to the gVisor stack instead of the legacy mixed stack. If you require the old behavior, manually set the stack in the configuration:

import { patchVergeConfig } from "@/services/cmds";

// Update TUN stack to legacy mixed mode if needed
await patchVergeConfig({
  tun: {
    enable: true,
    stack: "mixed",
  },
});

This invokes the Tauri command defined in src-tauri/src/cmd/patch_verge_config.rs, which persists the configuration to the new JSON-based cache system.

Technical Architecture Changes

Understanding the underlying code changes helps troubleshoot migration issues.

Tauri 2 Framework Migration

The rewrite moves from Electron to Tauri 2, splitting the codebase between:

• src-tauri/: Rust backend handling system proxy installation (src-tauri/src/core/sysopt.rs), service management, and IPC.
• src/: React/TypeScript frontend using SWR for state management (src/services/config.ts).

The IPC layer changed from custom sockets to Tauri's built-in command system (src-tauri/src/commands), making external CLI scripts incompatible.

Configuration System Overhaul

The runtime configuration (IVergeConfig) is now loaded lazily by src/services/preload.ts and cached in a JSON structure. The old static YAML approach is replaced by a dynamic system where:

• Profile storage logic resides in src-tauri/src/config/profiles.rs
• Frontend commands wrap Rust implementations in src/services/cmds.ts
• Configuration patching uses patchVergeConfig which calls src-tauri/src/cmd/patch_verge_config.rs

Service Mode Architecture

The new installer automatically detects administrator rights and chooses between service mode (system daemon) and sidecar mode (user-space process). This logic is implemented in src-tauri/src/core/sysopt.rs, replacing the old fixed service installation.

Automating Migration with Scripts

For advanced users managing multiple machines, automate the configuration transfer using Node.js:

import { promises as fsp } from "node:fs";
import path from "node:path";

async function migrateOldConfig() {
  const oldDir = path.join(process.env.HOME, ".config", "clash-verge");
  const newDir = path.join(process.env.HOME, ".config", "clash-verge-rev");

  // Ensure the new directory exists
  await fsp.mkdir(newDir, { recursive: true });

  // Copy the main yaml files
  for (const file of ["profiles.yaml", "config.yaml"]) {
    const src = path.join(oldDir, file);
    const dst = path.join(newDir, file);
    await fsp.copyFile(src, dst);
  }

  // Copy any custom extensions (merge / script)
  for (const dir of ["merge", "script"]) {
    const src = path.join(oldDir, dir);
    const dst = path.join(newDir, dir);
    if (await fsp.stat(src).catch(() => null)) {
      await fsp.mkdir(dst, { recursive: true });
      await fsp.cp(src, dst, { recursive: true });
    }
  }

  console.log("✅ Migration completed – launch Clash Verge Rev now.");
}

migrateOldConfig().catch(console.error);

This script mirrors the logic used by the official portable builder (scripts/portable.mjs, lines 27-34) to ensure configuration files land in the correct directory structure.

Troubleshooting Common Issues

Missing Profiles After Migration

If the application launches but shows no profiles, verify the file permissions and location:

ls -la ~/.config/clash-verge-rev/profiles.yaml

The Rust backend (src-tauri/src/config/profiles.rs) expects YAML files in this specific directory; symlinks from the old location are not automatically resolved.

Service Mode Failures

If system proxy toggling fails, the application may have installed in sidecar mode instead of service mode. Check the runtime configuration:

import { getRuntimeConfig } from "@/services/cmds";

const config = await getRuntimeConfig();
console.log(config.service_mode);

To switch modes, reinstall with administrator privileges or manually enable the service via the UI settings, which invokes src-tauri/src/core/sysopt.rs.

TUN Stack Compatibility

If TUN mode fails to initialize after migration, explicitly set the stack to mixed to match legacy behavior, as the default changed to gVisor in the new version.

Summary

• Clash Verge Rev is a complete Tauri 2 rewrite that does not inherit configuration from the original Electron-based Clash Verge.
• Manual migration is required: Copy profiles.yaml, config.yaml, and extension directories from ~/.config/clash-verge to ~/.config/clash-verge-rev.
• Uninstall first: Remove the old version completely to prevent service conflicts, then install from the Stable or AutoBuild release channels.
• Update TUN settings: The default stack changed from mixed to gVisor; manually configure if you need legacy behavior.
• Service architecture changed: The new version auto-selects between service mode and sidecar mode based on permissions, handled by src-tauri/src/core/sysopt.rs.

Frequently Asked Questions

Do I need to uninstall the original Clash Verge before installing Rev?

Yes. According to the official changelog in docs/Changelog.history.md, you must uninstall the original version before installing Clash Verge Rev. The new application will not read the old configuration files automatically, and running both versions simultaneously can cause service conflicts and port binding errors.

Where does Clash Verge Rev store its configuration files?

Clash Verge Rev stores configurations in ~/.config/clash-verge-rev on Linux/macOS and %APPDATA%\clash-verge-rev on Windows for standard installations. For portable builds, it uses a .config folder inside the application bundle, as defined in scripts/portable.mjs and referenced by src-tauri/src/config/profiles.rs.

Will my old merge and script extensions work in Clash Verge Rev?

Yes, but you must relocate them. Copy your merge and script directories from the old configuration folder to the new ~/.config/clash-verge-rev/ location. The new version renames these features to "扩展配置" (Merge Configurations) and "扩展脚本" (Script Extensions) and applies a new priority order (global → profile), but the underlying YAML structure remains compatible.

How do I fix TUN mode not working after migration?

If TUN mode fails after migrating, explicitly set the TUN stack to mixed to match the legacy default, as Clash Verge Rev defaults to gVisor. Use the UI settings or invoke the configuration patch via the frontend service layer (src/services/cmds.ts), which calls src-tauri/src/cmd/patch_verge_config.rs to persist the change.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}