Usage Guide

chrlauncher is designed to be unobtrusive. In standard daily usage, it runs briefly to manage its background state, handles updates if necessary, and then silently hands off execution to your web browser. This guide details how the underlying logic operates.

Launcher vs. Updater Mode

Depending on your workflow, chrlauncher can operate in two distinct modes:

1. Launcher Mode (Default)

This is the standard operation when you double-click chrlauncher.exe.

  1. It checks the elapsed time since the last update check against the ChromiumCheckPeriod setting in [Configuration](configuration.md).
  2. If an update check is due, it hits the API. If an update is found, it downloads and installs it.
  3. Crucially, once the check or installation is finished, it automatically launches the browser executable and exits its own process. It does not stay resident in memory while you browse.

2. Updater Mode

In this mode, chrlauncher acts strictly as a background maintenance tool. It will check for updates, download them, and unpack them—but it will not launch the browser when finished.

  • When to use this: This is perfect for setting up automated, scheduled background updates using Windows Task Scheduler, ensuring your browser is always up-to-date before you even click it.
  • How to enable: Set ChromiumUpdateOnly=true in chrlauncher.ini, or execute chrlauncher from the command line with the -update flag.

The Update Lifecycle

Understanding exactly what happens during an update helps in troubleshooting and customizing your portable environment. When an update check is triggered, the internal state machine executes the following steps safely:

  1. API Resolution: chrlauncher sends a WinHTTP request to the URL specified in ChromiumUpdateUrl (e.g., the Woolyss Chromium API). It requests JSON/String data matching your OS, Architecture, and chosen ChromiumType.
  2. Version Comparison: It reads the semantic version string from the API payload and compares it against the local binary version of your executable (e.g., chrome.exe inside the bin directory).
  3. Downloading: If the remote version is newer, the package is downloaded to a temporary file in the root directory (e.g., chrlauncher_hash.bin.tmp). A system tray icon will appear, and hovering over it displays the download percentage.
  4. Directory Rotation: Once the download completes, the old bin directory is safely rotated out. Depending on your configuration (ChromiumDeleteToRecycle), it is either permanently deleted or moved to the Windows Recycle Bin to prevent data loss in case of a bad update.
  5. Extraction: The new package is extracted natively using embedded LZMA (for .7z) or Miniz (for .zip) unpackers directly into a fresh bin folder.
  6. Post-Processing (Chrome++): If the Chrome++ portability hook is configured, its DLLs are injected into the new bin folder.
  7. Execution: Finally, chrlauncher.exe passes your custom command-line arguments to the new chrome.exe and shuts down.

Chrome++ Portability Enhancement

Standard Chromium builds possess a critical flaw when it comes to true portability: Hardware/OS-bound Cryptography.

Chromium encrypts sensitive user data—specifically Cookies and Saved Passwords—using Windows DPAPI (Data Protection API). DPAPI encrypts this data using your specific Windows User Account SID.

The Problem: If you copy your portable chrlauncher folder to a USB drive and open it on a completely different computer, DPAPI will fail to decrypt the data. You will find that all your active sessions are logged out, and all saved passwords are missing.

The Solution: Chrome++ Chrome++ is a third-party DLL hijack module. When placed next to chrome.exe, it intercepts Chromium's DPAPI calls and forces the browser to encrypt data using a hardcoded, portable key instead of the machine SID. This ensures your passwords travel with you.

How to integrate Chrome++ with chrlauncher:

Because chrlauncher deletes the bin directory entirely during an update, you cannot just drop Chrome++ inside the bin folder—it would be deleted on the next update! chrlauncher natively handles this with the ChromePlusDirectory feature.

  1. Download the latest release of Chrome++.
  2. Create a folder named chrome_plus inside your root chrlauncher directory (next to chrlauncher.exe).
  3. Place the downloaded version.dll and chrome++.ini files inside the new chrome_plus folder.
  4. Open chrlauncher.ini and ensure ChromePlusDirectory=.\chrome_plus is configured correctly.
  5. The Magic: Whenever chrlauncher updates Chromium, it will automatically copy version.dll and chrome++.ini from the chrome_plus staging directory into the brand new bin directory before launching the browser. Your portability is maintained effortlessly.

Troubleshooting Usage

  • Updates are looping or downloading every time: This usually happens if the downloaded binary's version metadata doesn't exactly match the API's reported version string. Check if the ChromiumType you selected is maintained properly by the upstream provider.
  • Extraction fails: Ensure you have enough free disk space. A Chromium .7z file may be 100MB compressed, but requires ~350MB of space to extract successfully.