Skip to content

Installing

Ryan Stoffel edited this page Oct 29, 2026 · 1 revision

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.

Supported computers

OS Architectures Installer
macOS Apple silicon only dmg
Windows x64 and arm64 exe
Linux x64 and arm64 AppImage

macOS

curl -fsSL https://raw.githubusercontent.com/ryan-stoffel/parallax/develop/scripts/install.sh | sh

The 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.

Windows

In PowerShell:

irm https://raw.githubusercontent.com/ryan-stoffel/parallax/develop/scripts/install.ps1 | iex

The 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.

Linux

curl -fsSL https://raw.githubusercontent.com/ryan-stoffel/parallax/develop/scripts/install.sh | sh

The 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.

Arch Linux (AUR)

The nightly is on the AUR as parallax-nightly-bin:

yay -S parallax-nightly-bin

It 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.

Release assets

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

What the first launch does

  1. On Linux and Windows, the app installs the parallax terminal command without asking. On macOS it asks "Use Parallax from your terminal?", since linking the command into /usr/local/bin takes your password. You can change this later in Settings > General > Terminal command. See Terminal.
  2. The app starts plxd on this computer.
  3. 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.

Requirements on the computer that runs agents

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.

Where files go

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.

Usage data

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

Uninstalling

  1. Remove the parallax command in Settings > General > Terminal command > Remove.

  2. Quit Parallax.

  3. If plxd runs as a login service, which Parallax Connect sets up, stop and remove it:

    ~/.parallax-plxd/plxd service uninstall

    On Windows, run %USERPROFILE%\.parallax-plxd\plxd.exe service uninstall.

  4. 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.

Clone this wiki locally