← Parallex

How Parallex works

Running an app twice means convincing macOS, and the app, that there are two of it. Here's exactly what Parallex does to get there, what it changes, and what it never touches.

The short version

Your original app is never changed. Everything Parallex makes lives beside it.
An instance is either a small launcher app that starts the original with its own data folder, or its own copy of the app with its own identity.
For copies, Parallex re-signs the copy and, for most apps, loads a small library into it so its files land in its own folder. That's the part that sounds alarming, so it's explained below, trade-offs included.
Removing an instance moves it and its data to the Trash (with two leftovers, listed below).

Two kinds of instance

Instance

A small app (under 2 MB) holding a launcher. It starts the original app with switches that point its data somewhere else, like --user-data-dir for Chrome and VS Code, or CLAUDE_USER_DATA_DIR for Claude. Nothing is loaded into the app. macOS still sees it as the original, so it shares the original's Dock icon.

Own copy

A copy of the app with an identity of its own: its own Dock icon, notifications, permissions and data. It's an APFS clone, so it shares most of its disk space with the original; its re-signed code is stored separately. It doesn't update itself: when the original updates, Parallex asks to refresh it. This is what makes App Store apps and most native apps separable.

An own copy: cloned, given its own identity, and started through Parallex's launcher.

Why a copy is re-signed

macOS knows an app by its bundle ID and its code signature. Giving the copy its own bundle ID changes the app, which breaks the developer's signature, so Parallex signs the copy again on your Mac, with a certificate it makes there the first time you make a copy. The certificate is trusted by nothing outside your Mac and kept in a keychain of Parallex's own, not your login keychain. The original keeps its signature.

Signing every copy with the same certificate matters because macOS remembers what you allowed an app (camera, microphone, screen recording, files and folders) by its signature. When the original updates and Parallex refreshes the copy, the copy keeps those permissions.

A copy's own updater is turned off. Left alone, it could install the developer's build over the copy, which would give the copy the original's identity and data again. Parallex refreshes the copy itself when the original updates.

What that costs: features tied to the developer's signature don't work in a copy. That means iCloud, push notifications that go through Apple, Sign in with Apple, keychain items shared between the developer's apps, website links that should open the app, and system extensions. Apple's own apps can't be copied at all.

Sign-ins a copy keeps in the keychain go to a keychain of its own, in its instance folder, so it never finds or replaces the original's, and keeps them through refreshes. Its password is kept beside it, readable only by you. A copy runs without the hardened runtime, so a program you run could reach its sign-ins through the copy itself; that's true of any app built that way, and a password in your login keychain wouldn't change it.

The library Parallex loads into a copy

macOS apps find their ~/Library folder (sign-ins, caches, cookies) by asking who you are, not by looking at $HOME. So to give a copy of an app that isn't sandboxed a Library of its own, the launcher loads a small library, libparallexhome, into it. It answers "where's my home folder?" (and $HOME) with the instance's folder:

The copy's own code names the library as well, so it loads even if macOS someday stops honoring the way the launcher inserts it.
It's active only in processes that run from inside the copy. Tools the app starts, like a shell or git, get your real home back.
Your Documents, Desktop, Downloads and dotfiles stay shared through links, so files you open or save are where you expect. The app's own folders, like ~/.vscode, stay with the copy.
It keeps a record of every file of yours outside the instance that the copy opens, creates or renames, so Verify Isolation covers everything since the copy first opened, not only what it has open at that moment.
Guard keeps the copy out of the original app's data: its Application Support folder, container, preferences, caches and cookies. The copy can't open, create, rename or remove anything there, even by its full path, and Verify Isolation lists each attempt. It's a safety net for the app's own code, not a sandbox against software set on getting around it.
Before a copy opens, the launcher checks that macOS loaded the library. If macOS refused it, the copy doesn't open, rather than quietly using your real data. If the check can't run at all, the copy opens, and Verify Isolation can check it while it runs.
The library is kept in Parallex's folder, ~/Library/Application Support/Parallex/lib, and every copy loads it from there.

App Store apps are sandboxed, so macOS already gives each one a container, and a copy with its own identity gets its own; no home library is loaded into them. Some keep their sign-in in containers shared by the developer's apps (WhatsApp does). For those, a second small library, libparallexgroups, shipped inside the copy, maps the app's requests for its shared containers to the copy's own.

One more change: Chromium and Electron apps keep an encryption key in your keychain named after the app ("Slack Safe Storage"). Each copy made since Parallex 0.13 gets its own key, rather than using the original's. Older copies keep using the original's key.

The trade-off, honestly

Re-signing drops Apple's "hardened runtime" from the copy. That's what lets Parallex's library load into it. It also means other software already running on your Mac as you could start the copy with code of its own inside it (or change the library in Parallex's folder, which every copy loads), and that code would run with whatever you've allowed the copy: camera, microphone, screen recording, its keychain items. The original is protected as before, so software would have to go after the copy specifically. It changes nothing for your other apps or for anything on the internet.

If you'd rather avoid it, use a plain instance (turn off Own identity): nothing is loaded into the app, and it keeps its developer's signature.

Checking it yourself

Verify Isolation (or parallex check <name>) lists the files a running instance has open and flags any that belong to the original app's data.
parallex doctor <app> says how an app would be separated before you make an instance.
An instance's Advanced section, in Parallex, shows where its app and its data are.
All of it is open source: the launcher, the home library and the containers library.

Other things Parallex installs

Parallex Links, for link routing, which is on by default during setup (Settings › Links turns it off): a small helper that passes sign-in links to the right copy. If you also turn on web links, it becomes your default browser and hands everything it doesn't route to the browser you had.
Parallex Web, for website instances: a small WebKit app, of which each website instance is its own copy.
The parallex command, if you install it from Settings › About.

When you remove a copy, two things stay behind: macOS keeps an App Store copy's containers until you delete them yourself (Parallex shows you which), and the copy's keychain entries remain in your keychain.