Repository navigation
Installing
Parallax is a desktop app with plxd, its daemon, inside. The install commands below install the latest nightly, and the app updates itself after that. To install a stable release instead, download it from the releases page, where it is the one marked Latest. Release Channels and Updates explains the difference.
| OS | Architectures | Installer |
|---|---|---|
| macOS | Apple silicon only | dmg |
| Windows | x64 and arm64 | exe |
| Linux | x64 and arm64 | AppImage |
curl -fsSL https://raw.githubusercontent.com/ryan-stoffel/parallax/develop/scripts/install.sh | shThe script downloads the newest nightly dmg and copies the app into /Applications, replacing any copy already there, then opens it. Quit Parallax before you run it. If Parallax is running, the script stops with "Quit Parallax, then run this again."
A nightly installs as Parallax (Nightly).app. A stable release is Parallax.app.
In PowerShell:
irm https://raw.githubusercontent.com/ryan-stoffel/parallax/develop/scripts/install.ps1 | iexThe script downloads the newest nightly installer for your architecture and runs it. It installs for your user, with no admin prompt. Open Parallax from the Start menu afterwards.
Windows builds are unsigned. See Troubleshooting if Windows blocks the installer.
curl -fsSL https://raw.githubusercontent.com/ryan-stoffel/parallax/develop/scripts/install.sh | shThe script puts the AppImage at ~/.local/share/parallax-nightly/Parallax.AppImage, links ~/.local/bin/parallax-nightly to it, and adds a launcher entry and icons from the AppImage. Open Parallax from your app launcher or run parallax-nightly. The file name has no version, so the app's updater replaces it in place.
The AppImage uses the static AppImage runtime, so it doesn't need libfuse2.
The nightly is on the AUR as parallax-nightly-bin:
yay -S parallax-nightly-binIt unpacks the AppImage into /opt/parallax-nightly and adds a parallax-nightly command. Your AUR helper updates it, not the app. Stable releases aren't on the AUR.
Each release on the releases page has these files. A nightly's <version> ends in -nightly.
| File | What it is |
|---|---|
parallax-<version>-mac-arm64.dmg |
macOS installer |
parallax-<version>-win-x64.exe, parallax-<version>-win-arm64.exe
|
Windows installers |
parallax-<version>-linux-x86_64.AppImage, parallax-<version>-linux-arm64.AppImage
|
Linux apps |
parallax-plxd-<version>-<os>-<arch> and its .sha256
|
plxd on its own, for a computer without the app |
parallax-<version>-linux-<arch>-sandbox-sources.tar |
Sources of the bwrap and socat built into Linux's plxd |
SHA256SUMS |
Checksums of every file, added once all five builds have succeeded |
The zip, .blockmap, and .yml files are for the app's updater.
To check a download on Linux, put it in the same folder as SHA256SUMS and run:
sha256sum --ignore-missing -c SHA256SUMS- On Linux and Windows, the app installs the
parallaxterminal command without asking. On macOS it asks "Use Parallax from your terminal?", since linking the command into/usr/local/bintakes your password. You can change this later in Settings > General > Terminal command. See Terminal. - The app starts
plxdon this computer. - On a fresh install, setup opens with five steps: Account, Agents, Import, Tour, and Start.
- Account signs you in to a Parallax account. Choose Not now to skip it.
- Agents finds the agents installed on this computer and turns on the ones that are signed in.
- Import brings in past sessions from other apps.
- Start offers Start a thread or Explore on my own.
Skip setup, the X in its corner, ends it early. Setup doesn't show again once you finish or skip it.
Then sign in to at least one provider on the computer that runs the work. Settings > Providers does this for any connected computer. See Providers.
| Requirement | Why |
|---|---|
git on PATH
|
Threads run in git worktrees |
| For a CLI agent, its CLI, signed in | Parallax runs your own claude, codex, and other CLIs with your subscription |
| Node.js 22.16 or newer, and npm | Claude Code runs through the Claude Agent SDK, which plxd installs with npm the first time it's needed |
| Node.js 22.13 or newer, and npm | The same, for the Cursor SDK |
API keys are stored in the macOS login Keychain, or the Secret Service on Linux. Windows has no key store yet. See Troubleshooting.
| What | Where |
|---|---|
| The app |
/Applications on macOS. A per-user install on Windows. ~/.local/share/parallax-nightly on Linux, or /opt/parallax-nightly from the AUR |
| plxd's data (threads, worktrees, logs) |
~/.parallax (%USERPROFILE%\.parallax on Windows) |
| The app's own data | ~/.parallax/desktop |
| The copy of plxd that a login service, an SSH install, or the terminal-only install runs | ~/.parallax-plxd |
A computer that ran an older version of Parallax and has no ~/.parallax keeps using the folder that version made: ~/Library/Application Support/parallax on macOS, $XDG_DATA_HOME/parallax or ~/.local/share/parallax on Linux, or %LOCALAPPDATA%\parallax on Windows. Settings > Storage shows the folders this computer uses. PLXD_DATA_DIR moves plxd's data folder.
Nightly and stable builds share both data folders.
The installed app sends one app_active event to PostHog at launch and once a day while it runs. It carries a random id made for the install, the app's version and channel, and the OS and architecture. It carries no account, name, path, prompt, or code, and PostHog adds no location from it.
To turn it off, set DO_NOT_TRACK=1 in the app's environment. Any value other than empty or 0 turns it off. On macOS an app opened from the Dock or Finder doesn't read your shell profile, so run this and restart the app:
launchctl setenv DO_NOT_TRACK 1-
Remove the
parallaxcommand in Settings > General > Terminal command > Remove. -
Quit Parallax.
-
If plxd runs as a login service, which Parallax Connect sets up, stop and remove it:
~/.parallax-plxd/plxd service uninstallOn Windows, run
%USERPROFILE%\.parallax-plxd\plxd.exe service uninstall. -
Remove the app:
| Install | How to remove it |
|---|---|
| macOS | Delete it from /Applications
|
| Windows | Uninstall Parallax from Apps & features in Windows Settings |
| Linux, install script | Delete ~/.local/share/parallax-nightly, ~/.local/bin/parallax-nightly, and ~/.local/share/applications/parallax-desktop.desktop
|
| Linux, AUR | yay -R parallax-nightly-bin |
| Terminal only | Delete ~/.local/bin/parallax and ~/.parallax-plxd
|
Your threads, worktrees, and logs stay in the data folder until you delete it. Deleting it deletes your thread history.
Start
Using Parallax
Your computers
Maintenance
Contributing