Repository navigation
Remote Access
Besides SSH (Hosts), other devices reach a computer's plxd in four ways. All are off by default and set in Settings > Connections.
| Way | For | Port | Who gets in |
|---|---|---|---|
| Parallax Connect | Your computers on one Tailscale tailnet, and the iOS app | 7340 on the Tailscale address | Your own untagged Tailscale devices. Nothing to pair |
| Same network | Computers without Tailscale, and the iOS app | 7341, HTTPS | Devices paired once with a code |
| Open in a browser | The web app | 7341, HTTPS | Browsers paired once with a code |
| Reach from anywhere | Your devices through Parallax Relay | Outbound only | Devices signed in to your Parallax account and paired |
Parallax Connect links your computers over Tailscale. Every computer sees every other computer's threads, and a computer set up from another one connects to all of them by itself.
You need:
- Tailscale on each computer, signed in as the same Tailscale user. Tagged devices and devices shared from another tailnet can't join.
- SSH on each computer you add from another one: Remote Login on macOS, OpenSSH Server on Windows, or sshd on Linux. It's needed only for the first install.
- In Settings > Connections, turn on Parallax Connect. Add a computer opens and lists your devices on Tailscale.
- Choose Set up next to a computer. It lists what happens: it signs in over SSH, installs Parallax and
plxd, and turns on Parallax Connect. - Choose whether it's Headless, which installs
plxdwithout the app. Linux always getsplxdalone. Set SSH user if your ssh config doesn't name one. - Choose Install. A terminal shows the install, and asks for the SSH password there if one is needed.
The install downloads the newest build of this app's channel from GitHub and checks each download's SHA-256. It installs plxd's login service, turns Connect on, and waits for port 7340 to answer. On Windows it also allows plxd through Windows Firewall on TCP 7340 when it can. On Linux it turns on lingering, so plxd runs without anyone logged in.
A device that already runs Connect, but that this app turned off or removed, shows Add instead of Set up.
While Connect is on, Settings > Connections lists this computer and each Connect computer, with its OS, address, plxd version, latency, uptime, and running agents.
- The switch on each computer decides whether this app uses it. Off drops its connection and its threads here.
- Its menu has Icon, Rename, and Remove from this device. Icon and Rename are saved on that computer, so every computer shows the same.
- Remove from this device only stops this app connecting. Nothing on that computer changes, and Add computer brings it back.
A Connect computer's terminals, installs, and provider sign-ins go over ssh to its Tailscale address.
The app runs its own copy of plx-connect. On a computer without the app, run it with Node 20 or newer:
npx plx-connect setup --channel nightly # set up this computer
npx plx-connect add <device> # set up another device over SSH--channel is stable or nightly, and defaults to stable. Use the channel your other computers run.
plxd connect on and plxd connect off change the setting without the app. A running plxd follows within 10 seconds.
-
plxdlistens on port 7340 on its own Tailscale IPv4 address only, never on the LAN or the internet. - For each connection it runs
tailscale whoison the peer and serves it only when the peer is the same Tailscale user, neither side is tagged, and the peer isn't this computer. Everything else is closed and logged. - There is no token. Tailscale encrypts the traffic and proves who is on the other end.
Any process on your other untagged devices can reach plxd while Connect is on.
Use this for a computer without Tailscale.
On the computer to reach:
- In Settings > Connections > Same network, turn on Pair computers on this network.
- Choose Pair a device. It shows a code such as
7KQ-4M2.
On the other computer:
- Under Computers on this network, choose Add computer.
- Pick the computer by name, or choose Enter an address instead.
- Enter the code and choose Pair.
A code works once, for 5 minutes. Five wrong tries lock it. While a code is showing, the computer advertises its name on the network over mDNS, and it stops once the code is used, locked, or expired.
A paired computer has full control: it can run agents and commands with full access, open terminals, change settings, and pair other computers. Pair only your own computers. Each paired device is listed under Same network with Revoke, which works even with pairing turned off. On the other side, Remove forgets the computer.
-
plxdlistens on port 7341 of every IPv4 address and speaks only HTTPS. It closes, before reading anything, any connection that isn't from a private, link-local, loopback, or Tailscale address. - Each computer has its own self-signed certificate (ECDSA P-256). Pairing uses SPAKE2 with the code to confirm the certificate's fingerprint, and the paired device then pins that fingerprint. It sends nothing to a computer that shows another certificate. Someone in the middle gets one guess per try and never learns the fingerprint.
- Pairing gives a session bound to a key the device holds, so a stolen token is useless without the key.
plxdstores the token hashed.
Details: 0065.
plxd serves the app to a browser over the same HTTPS listener.
- Turn on Pair computers on this network, then Open in a browser.
- Choose Pair a device. Settings shows the address to open, such as
https://192.168.1.20:7341. - Open it in the browser and enter the code.
The browser warns about the certificate, since it's self-signed. Use the computer's Tailscale address where you can. On the LAN, continue only if the SHA-256 fingerprint the browser shows matches the one under Open in a browser, or trust the certificate in your OS first. Otherwise someone on the network could pose as the computer and take the code.
The web app reaches only the computer that served it. It has no other hosts, updater, editors, file pickers, or account. Turning Open in a browser off disconnects paired browsers until it's on again.
The web app's files come from the desktop app's install, so a computer that runs plxd without the app doesn't serve one.
Parallax Relay lets your devices reach a computer from anywhere, and gives its webhooks a public address. It runs on Cloudflare Workers.
The hosted relay isn't deployed yet. Until it is, Reach from anywhere can't connect, and the iOS app's notifications arrive only while the app is open (Mobile).
To turn it on, sign in to a Parallax account (below), turn on Pair computers on this network, then turn on Reach from anywhere. Then pair each device once, as on the same network. The relay route is tried after a computer's LAN and Tailscale addresses.
What the relay sees:
-
Threads: nothing. It passes the device's TLS connection to
plxd's own pinned certificate, so it carries only encrypted bytes. It can't read or change a thread, or pose as your computer. It can drop or delay connections, and learn when your computers are online. -
Webhooks: everything a sender sends, as any public webhook endpoint does, tokens included. It forwards each request to
plxd, which checks the token and signature. If you don't want the relay's operator able to fire a task, give the task a signature secret, and have the task check what it acts on. - Notifications: only that a run needs you, finished, or failed, with the run's id. No title or text.
Limits:
- An account holds 10 computers on the relay. Settings lists them under Reach from anywhere, each with Remove.
- A computer's relay traffic is capped at 2 GiB a day.
Turning Reach from anywhere off disconnects the computer but keeps its registration, so its webhook URLs stay the same. Remove deletes the registration.
Details: 0068.
A webhook task's URL depends on what's on:
| On | Webhook URL |
|---|---|
| Reach from anywhere, connected | The relay's public URL |
| Pair computers on this network | https://<LAN address>:7341/api/hooks/... |
| Neither | No URL |
While the computer is away, the relay holds its webhooks for up to 24 hours and delivers them in order when it reconnects. A body can be up to 1 MiB. See Triggers.
The desktop app works without an account. You need one for Reach from anywhere and the iOS app.
Sign in from Profile in the sidebar footer: Sign in, or Create an account. Clerk's page opens in your browser, with GitHub, Google, Apple, or email. Signed in, the menu has Manage account and Sign out. Name, picture, email, and password changes open Clerk's account pages.
- The app keeps the session encrypted with the OS keychain. On Linux without a keyring it keeps it in memory only, so you sign in again after each launch.
- The browser never holds a token.
- Sign out signs out this computer only.
Details: 0067.
Start
Using Parallax
Your computers
Maintenance
Contributing