Offline Migration and Backup Guide for UJAM Plugins

This guide outlines the technical protocol for executing a fully localized, offline migration of your UJAM product catalog (often exceeding 170 GB). By manually migrating core binaries, .blob payloads, and specific JSON manifests, you can bypass massive network downloads when moving to a new workstation or reinstalling your OS.

For more information on why the background daemon is necessary for modern (Type 1) plugins, see: Do I really need the UJAM App?

Phase 1: Archival and Data Backup

Before decommissioning your original system, back up the following directories to an external staging drive. Ensure you maintain the exact folder structures.

For a comprehensive list of all paths, refer to our Default File Locations for UJAM Products article.

1. Audio Payloads (.blob) & Detection Manifests:

• Windows: C:\ProgramData\UJAM\
• macOS: /Library/Application Support/UJAM/
• Critical: You must back up the nested assets folder containing the buildInformation.json files. The UJAM App polls this exact file to detect an installation. Copying only .blob files will result in a "Not Installed" status.

2. Plugin Binaries (.vst, .vst3, .component, .aaxplugin):

• Back up your VST2, VST3, AU, and AAX files from their respective OS system directories.

3. User Presets:

• Windows: %APPDATA%\UJAM\ (Note: %APPDATA% resolves to C:\Users\<username>\AppData\Roaming)
• macOS: ~/Library/Application Support/UJAM/<plugin-name>/

Phase 2: Target Deployment

On your new operating system or physical workstation, reverse the archival process.

1. Install the UJAM App: Before transferring files, download and install the latest version of the UJAM App on your new machine. Do not log in yet.
2. Inject Plugin Binaries: Manually deposit the compiled plugins back into their strictly mandated OS directories (e.g., VST3 files must go to %ProgramFiles%\Common Files\VST3\ on Windows or /Library/Audio/Plug-Ins/VST3/ on macOS). Deviations will cause the DAW to ignore them.
3. Deploy Payloads and Manifests: Deposit the .blob files and the nested assets/buildInformation.json manifests into the target machine's C:\ProgramData\UJAM\ (Win) or /Library/Application Support/UJAM/ (Mac) directory.

At this stage, the UJAM App will detect the buildInformation.json and read the software as "Installed". However, authorization will fail due to hardware fingerprinting.

Phase 3: License Synchronization & .ops Regeneration

UJAM authorization utilizes .ops files—encrypted JSON arrays containing a hardware fingerprint (CPU ID, Motherboard Serial, MAC Address). Moving these files to a new machine will cause a hash mismatch, permanently sandboxing your plugins into Trial Mode.

You must force the UJAM App to generate a new token for your new hardware:

1. Purge Legacy Tokens: Navigate to the local user directory and delete all existing .ops files.

• Windows: %APPDATA%\UJAM\
• macOS: ~/Library/Application Support/UJAM/

2. Initialize Daemon: Launch the UJAM App and log in using the exact single email account registered to your licenses.
3. Execute Handshake: Click the "Refresh now!" button at the bottom of the App interface.
4. Regeneration: The absence of the old .ops files triggers the App to query the UJAM License Server and generate fresh, mathematically valid .ops tokens locked to your new hardware.

For an in-depth explanation of this subsystem, see the UJAM Plugin Authorization Guide: Comprehensive Manual.

Troubleshooting: macOS "Silent Failures"

If you are migrating to a new Mac (via manual copying or Migration Assistant) and the plugins remain in Trial Mode even after clicking "Refresh now!", you are likely experiencing a POSIX permission mismatch.

If your new macOS user account has a different UID, the OS will restrict the UJAM App's write access, preventing it from saving the newly generated .ops files.

• Solution: You must forcefully reclaim ownership of the UJAM directories using elevated Terminal commands (sudo chown and chmod).
• Full Instructions: Fixing macOS Write Permissions for UJAM Plugins

Future-Proofing: External SSDs and Symbolic Links (Symlinks)

To isolate the massive 170+ GB payload from your OS boot drive and create an "update-safe" environment, we highly recommend storing your .blob payloads on an external SSD and using OS-level Symbolic Links to point your system to the drive.

⚠️ CRITICAL: The ExFAT Catastrophe

Do NOT format your external SSD as ExFAT. ExFAT fundamentally lacks the architecture for Symlinks, does not support POSIX permissions, and is a documented cause of catastrophic DAW freezing.

• For more information on system crashes caused by ExFAT, read: DAW Freeze | exFAT Issues with Usynth and Virtual Pianist (macOS)
• Required Formats: Format your drive to NTFS (Windows exclusive), APFS / Mac OS Extended (macOS exclusive), or use third-party bridging drivers if cross-platform compatibility is needed.

External Validation & Further Reading on ExFAT Limitations:

• Understanding File Systems and Drive Formatting (Kingston Technology)
• Is it possible to create symbolic links on exfat filesystem? (Ask Ubuntu)
• ExFat or MacOS Extended (Journaled) for External HDD (Reddit - r/mac)

Setting Up Symlinks

Using standard "shortcuts" or "aliases" will not work; the plugins will fail to parse the audio data. You must use kernel-level Symlinks (mklink on Windows, ln -s on macOS).

Please follow the precise command-line instructions in our dedicated guides:

• Windows Users: Managing Large .blob Files Using Symbolic Links on Windows
• macOS Users: Managing Large .blob Files Using Symbolic Links on macOS