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

Hosts

A host is a computer that runs plxd. Every thread runs on one host, with that host's repositories, provider sign-ins, and files. The app connects to several hosts at once, and threads from all of them show in one sidebar.

The app calls hosts computers. They're all in Settings > Connections.

Kind How the app reaches it Set up in
This computer The local plxd, which the app starts Nothing to set up
SSH host ssh <host> plxd attach, with your own ssh config and keys Settings > Connections > SSH hosts
Parallax Connect TCP port 7340 on the computer's Tailscale address Settings > Connections > Parallax Connect, see Remote Access
Same network HTTPS on port 7341, paired once with a code Settings > Connections > Same network, see Remote Access

To start a thread on another host, pick it in the composer's Computer menu. A host that lacks the repository you picked says Clones and the repository's name, and picking it clones the repository there.

Sign in to providers on the host that runs the work. Settings > Providers has a picker for each host. See Providers.

This computer

The app starts this computer's plxd and keeps it connected. Settings > Connections shows its name, the Local plxd row with its status and version, and Rename this computer.

SSH hosts

Use an SSH host for a machine you already reach with ssh, such as a Mac mini or a Linux server.

  1. Open Settings > Connections and choose Add host under SSH hosts.
  2. In Add a computer over SSH, enter the SSH host or alias. Hosts from your ssh config and known_hosts are suggested as you type. Username and Port are optional and default to your ssh config.
  3. Choose Add computer.

Each host has Edit and Remove. Edit also changes its name.

The app runs ssh in batch mode, so ssh never prompts. A host that needs a password, or whose host key ssh doesn't trust yet, fails with a Sign in button. Sign in opens a terminal where ssh asks, then keeps that ssh connection open for the app to reuse. Sign in isn't offered when the app runs on Windows, whose OpenSSH can't share a connection.

The app's ssh is ssh on your PATH. To use another program, set ssh in the app's settings.json in its user data folder by hand.

How the app starts plxd over SSH

The app runs plxd attach on the host. When plxd isn't on the host's PATH, it tries these in order:

  1. ~/.parallax-plxd/plxd
  2. ~/.local/bin/plxd
  3. plxd inside Parallax.app or Parallax (Nightly).app, in /Applications or ~/Applications

plxd attach connects to plxd on that host, and starts it first if it isn't running:

  • With plxd's login service installed (below), it starts the service.
  • Otherwise it starts plxd serve detached, in a new session, so closing the ssh connection doesn't stop it. Its output goes to logs/plxd.log in the data folder.

It waits up to 10 seconds for plxd to answer, then passes bytes between ssh and plxd until the connection ends. It never stops a running plxd.

When a host fails to connect, the exit code says why:

Code Meaning
4 plxd attach ran but couldn't reach or start plxd
127 No plxd was found on the host
255 ssh itself failed, such as a refused login or an unknown host key

Details: 0007, 0010.

Installing plxd on an SSH host

When a host has no plxd, its row shows Install plxd. When its plxd is older than the app, it shows Update plxd.

Either one downloads the plxd release that matches the app's version from GitHub, checks its SHA-256 against the release, checks that it runs, and puts it in ~/.parallax-plxd/plxd with a plxd.version file beside it. Update then restarts plxd, which stops agents running there.

  • Hosts: macOS on Apple silicon, and Linux on x64 or arm64. Intel Macs and Windows hosts aren't supported.
  • The host needs curl or wget and HTTPS access to github.com.
  • A development build of the app doesn't offer either button, since it has no release to install.

Details: 0065.

Keeping plxd running

plxd service installs a per-user login service that starts plxd and restarts it after any exit:

OS Service
macOS A LaunchAgent, which starts once you log in
Linux A systemd user unit. Installing it turns on lingering, so plxd starts at boot and keeps running after you log out
Windows A scheduled task that starts at logon and starts plxd again within 5 minutes of an exit. It needs no admin rights
plxd service install
plxd service status
plxd service uninstall

While Parallax Connect is on, the app keeps this computer's plxd under the service, so other computers reach it after the app quits or the computer restarts. The service runs ~/.parallax-plxd/plxd (%USERPROFILE%\.parallax-plxd\plxd.exe on Windows), which the app keeps current.

Details: 0072.

The data folder

plxd keeps everything in one folder per user:

  • ~/.parallax on macOS and Linux
  • %USERPROFILE%\.parallax on Windows

A computer that had Parallax before this location, and has no ~/.parallax, keeps using the older folder: ~/Library/Application Support/parallax on macOS, $XDG_DATA_HOME/parallax or ~/.local/share/parallax on Linux, or %LOCALAPPDATA%\parallax on Windows.

--data-dir or the PLXD_DATA_DIR environment variable moves it.

Entry What it holds
plxd.sqlite3 The store: threads, Projects, and the event log
plxd.sock The socket the app and plxd attach connect to. Windows uses a named pipe instead
plxd.lock Held while plxd serve runs, with its pid
logs/plxd.log The log
worktrees/ Threads' git worktrees
uploads/ Files attached to messages
tools/ Tools plxd installs for itself, such as gh, and on Linux the bwrap and socat the sandbox uses

The plxd binary that installs and updates write is in ~/.parallax-plxd, outside the data folder.

Details: 0009, 0023.

The worker sandbox

Some Claude Code runs go in Claude Code's own OS sandbox: a run that doesn't send its approval requests to you and isn't in Full access. Threads you start, whose approvals come to you, and runs in Full access don't use the sandbox and run on every OS.

Inside the sandbox, an agent's commands:

  • write only to the run's worktree, its Project's shared context folder, and its own temp folder
  • can't write git metadata
  • can't read credential stores such as ~/.ssh, ~/.aws, ~/.config/gh, and ~/.npmrc, or the data folder apart from uploads
  • have network access
OS Sandbox
macOS Seatbelt
Linux bubblewrap, socat, and Claude Code's seccomp filter. A release plxd brings its own bwrap and socat. plxd checks before each run that the sandbox works
Windows None. Claude Code has no sandbox on native Windows, so these runs are refused

On Ubuntu 24.04 and later, AppArmor blocks bubblewrap until you install the distro's bubblewrap and add the AppArmor profile from Claude Code's sandboxing docs. The refusal message says so.

On Windows, run plxd for Linux inside a WSL2 distro and add that distro as an SSH host. Runs there use the Linux sandbox. WSL1 isn't supported.

Other providers run only as full agents in threads, with no sandboxed runs.

Details: 0013, 0023.

A Project's threads on another computer

A Project's child threads run on the host that holds the Project. Choosing another computer for them is designed in 0057, but released plxd builds have it turned off. See Projects.

Updating connected hosts

In a release build, once this computer's plxd runs the app's version, the app updates every connected host whose plxd is older: SSH hosts, Parallax Connect computers, and computers paired on the same network. It tries each host once per launch.

  • A host whose plxd can update itself downloads the new plxd from GitHub, checks it, and restarts into it once no agent's turn is running there. This works on macOS, Linux, and Windows.
  • An SSH host with an older plxd gets the SSH install above, once no agent is running there.
  • A host that can do neither gets a message. On macOS and Windows it says to update Parallax on that computer. On Linux it gives the command to run there, npx plx-connect setup --channel <channel>.

A notice says Updated plxd on the host, or Couldn't update plxd with the reason and Retry.

The sidebar footer's Update button lists everything that can update: the app, each host's plxd, and each host's Claude Code and Codex. Its dialog has Update all, or Update N selected after you untick some. When running threads would be interrupted, it says how many and offers Continue threads after restarts.

Each host needs HTTPS access to github.com to download plxd.

Details: 0066, 0072, Release Channels and Updates.

Clone this wiki locally