Self-hosting

What you need

• A Linux or macOS machine for the relay, always on, reachable by your machines and phones: on a private network such as WireGuard or Tailscale, or on the internet with a TLS certificate.
• pi on each machine whose sessions you want to reach, with git and npm, which pi uses to install packages. Running pi in tmux or herdr lets PiRC show where each session runs and open new ones beside it.
• PiRC's app for iPhone, iPad or Android, and optionally the web app, which runs on a server of yours.

Downloads

The relay, the web app and the source arrive with the first public release, and the apps in the App Store and Google Play. The links will be here.

1. The relay

Install the relay as a service (systemd on Linux, launchd on macOS) and set where it listens and its TLS certificate in its settings file. The guide in the release covers both, a proxy in front, upgrades and backups. Then check it:

curl https://relay.example.org:8443/healthz   # prints OK

2. The extension, on every machine that runs pi

Install it in pi, then issue a token for the machine on the relay; --url prints the whole line to run in that pi:

pirc-relay add-host --url wss://relay.example.org:8443 --label laptop
# prints: /pirc enrol wss://relay.example.org:8443 <token>

Run that line in pi, and /pirc status shows the connection. A machine can also ask to join with /pirc enrol <relay-url> alone, to be approved on the relay or in the app after checking that its key matches what /pirc status shows.

3. Your phone

pirc-relay add-client --url wss://relay.example.org:8443 --label phone

This prints a pirc://join link and a QR code. Scan it with your phone's camera or from PiRC's app, then confirm in the app. From then on, the app can invite your other phones and approve new machines.

4. The web app (optional)

The web app is a small server of yours that serves the page and signs you in with a passkey. It joins the relay as one more client, and you add a passkey with a one-time link it prints.

Notifications

PiRC's apps are woken through our push gateway at push.pirc.dev, which your relay calls when a session finishes or needs you. The push carries nothing: your phone connects to your relay and writes the notification itself. The gateway learns only which relay asked to wake which phone, and when; the privacy policy has the details. Without it, everything works but notifications.

Help

Questions and problems: see support.