Pairing and remote access

The Weaver daemon runs on your Mac or Linux machine. The steps below are written for a Mac. Everything else (the desktop app on another Mac, the iPhone or iPad app) is a client that connects to it. Your sessions, files, and agents stay on the machine that runs the daemon. Remote access reaches that machine. It does not move your work to the cloud.

For a remote client to work, the daemon’s machine must be awake, online, and running Weaver.

How the daemon listens

The daemon accepts WebSocket connections on port 8790 by default. On macOS, if that port is taken, the packaged app picks a free port between 8792 and 8891 and keeps it across restarts, so paired devices keep working.

In production builds the daemon listens on all network interfaces, not only on localhost. Any machine on your network can open a connection to that port, but nothing gets in without credentials:

• The desktop app on the same Mac uses an owner token stored on disk. That token never leaves the machine.
• Every paired device holds its own credential, minted once during pairing. It proves itself on every connection, and the connection is then encrypted end to end (ChaCha20-Poly1305, keys derived per connection).

The daemon also announces itself on the local network over Bonjour (mDNS) with its version, an instance id, and the machine’s host name.

Pair a phone or iPad

1. On the Mac, open Settings → Devices.
2. Under Connect mobile, click Show QR code.
3. On the phone, open Pix and tap the scan button. Allow camera access when asked.
4. Point the camera at the QR code.

The phone tries each route in the code in order and gives up after 15 seconds. When it succeeds, the Mac shows the phone’s name and the phone opens your sessions.

The QR code contains a one-time secret. Anyone who scans it before you do can pair. Keep it off shared screens. The code works once; showing a new code cancels the previous one.

A Mac that is itself paired to this daemon as a remote desktop can also show a mobile QR code.

Pair another Mac

Mac-to-Mac pairing uses an invitation link instead of a QR code.

On the Mac you want to control (the one running the daemon):

1. Open Settings → Devices.
2. Under Let another Mac control this Mac, click Create invitation.
3. Click Copy link and send the link to the other Mac over a private channel.

On the other Mac:

1. Open the link. Pix opens Settings → Devices with the link filled in. You can also paste it under Connect another Mac.
2. Click Connect.

The invitation is valid for five minutes, works once, and allows five attempts. It carries a six-digit code, the daemon’s identity and host name, and its routes. The code is checked with a password-authenticated key exchange (OPAQUE), so it never crosses the network in the clear.

A phone that is already paired to the daemon can also create a Mac invitation.

Pairing another Mac stores the connection credential in the system’s secure storage. If secure storage is unavailable, Weaver disables Mac-to-Mac pairing and says so in Devices.

Once paired, the other Mac lists the daemon under Saved Machines. Pick This Mac, a saved machine, or All Machines to see sessions from every machine in one list.

See and revoke devices

Settings → Devices → Connected devices lists every device paired to this daemon: its name, its kind (mobile or desktop), whether it is connected now, and when it was paired.

Click Revoke to remove a device. The daemon deletes its credential and closes its open connections immediately. A revoked device must pair again to reconnect.

From the Mac that runs the daemon you can revoke any device. A paired device can revoke only itself.

Routes: LAN first, then relay or Tailscale

A paired device does not store one address. The daemon publishes an ordered list of routes and the client tries them in that order, failing over on its own:

1. LAN. A direct connection on your local network. Fastest. No setup.
2. Your preferred remote route. The Pix relay by default.
3. The other remote route.

Set the preferred remote route in Settings → Devices → Remote access → Preferred route. Choosing Tailscale only swaps steps 2 and 3. LAN always stays first. The same pane shows the status of each route, for example “Connected to the Pix relay.” or “Tailscale is not running on this host.”

The Pix relay

The relay is the default way to reach your Mac from another network, such as a phone on cellular. It needs no account, no port forwarding, and no VPN.

It runs on Cloudflare (a Worker with one Durable Object per daemon). The daemon keeps one outbound secure WebSocket open to the relay. When a paired client connects to the relay, the relay hands it a short-lived tunnel to your daemon and copies frames between the two.

Only Weaver traffic goes through the relay. It is not a VPN and does not route anything else on your phone or Mac.

Downloads, video previews, and simulator streams use separate HTTP paths and work only over a direct route (LAN or Tailscale), not over the relay.

What the relay can see

Pairing, device proof, revocation, and encryption run between the client and the daemon. The relay cannot decrypt what you send. It does see:

• the source IP addresses of the daemon and the client, and when they connect
• the daemon’s public route identifier and the lifecycle of each tunnel
• the size of each encrypted frame and total traffic volume

The relay does not store route credentials, session state, or message contents. It keeps no copy of the frames it forwards.

The daemon counts relay usage locally (connection requests, messages, bytes) and shows it in Settings → Usage. If product analytics are on, it also sends occasional aggregate checkpoints of those counts. See Analytics and privacy.

Tailscale

If Tailscale is running on the daemon’s machine, the daemon finds it and adds the machine’s Tailscale addresses (and its MagicDNS name, when MagicDNS is on) to the route list. The daemon looks for the tailscale command in /opt/homebrew/bin, /usr/local/bin, inside /Applications/Tailscale.app, and on your PATH.

To use this route, the client device must be signed in to the same tailnet. Traffic goes over Tailscale’s own encrypted network. The Pix relay is not involved.