Connect from your iPhone or iPad

Before you start

RavenRemote is coming soon; there is currently no public installation or TestFlight invitation on the download page. These instructions are for people who already have a development build of the iOS app.

Keep Raven running on the Mac and keep the Mac awake. The remote listener starts automatically when signed in to Raven; manual pairing can also start it from the palette. For a direct connection, put the Mac and phone on the same Wi-Fi network. Allow Local Network access when iOS asks; discovery and direct connections need it.

Pair your phone

1. On the Mac, open the command palette with ⌘K and choose Start Remote Listener.
2. Open the palette again and choose Pair Phone (QR). A pane displays the pairing code.
3. Scan the code with your phone’s camera and open the raven:// link in RavenRemote. It supplies the Mac’s addresses, ports, pairing token, and TLS certificate fingerprint.

You can also start the listener and display the code from a terminal on the Mac:

raven-term remote start
raven-term pairing --qr

If scanning is inconvenient, run raven-term pairing, transfer its url privately to your phone, and choose Paste pairing link in RavenRemote. The pairing link grants access to your terminal: keep the link and QR code private.

Nearby Mac discovery helps you find an address, but you still need the pairing token. Using the pairing link also sets the certificate pin, so it is the easiest way to get the connection details right.

Choose how to reach your Mac

• On the same Wi-Fi: use the paired TLS connection on port 18486. No VPN is required. Guest networks that isolate devices can prevent this connection.
• Over Tailscale: connect the Mac and phone to your tailnet. Pairing includes available tailnet addresses. The separate port 18485 is for the plain connection protected by Tailscale; use TLS on 18486 for the paired TLS path.
• Over the internet with a relay: configure a relay reachable by both devices. The Mac connects outward to it, so you do not need to forward a port on your home router.

A pairing link includes available connection candidates. RavenRemote tries them and uses a reachable address, preferring a direct local connection when available. After adding a relay, pair again to give the phone the updated address list.

Connect through a relay

A relay can run in raven-hub or in the standalone raven-relay server. You or your service operator must provision its address and a relay token for your Mac when using a self-hosted relay. Current Raven releases also register signed-in machines with Raven’s hosted relay automatically. Sign in to the same account in RavenRemote and approve the new device with raven-term devices approve on a trusted machine, comparing the six-digit codes on both devices. For desktop access to a server through the hosted relay, follow the remote-host guide.

Add the operator’s values to ~/.config/raven-term/config.toml on your Mac:

[remote]
relay = "office.relay.example.com:8443"
relay_name = "office"
relay_token = "<relay token supplied by your operator>"

The hostname, port, and tenant name above are examples. Use your actual relay details. The relay token is separate from the phone’s pairing token. Instead of storing relay_token in the config, you can put its value in ~/.raven/relay-token and restrict that file to your user with chmod 600.

Restart the remote listener, then display a new pairing code:

raven-term remote stop
raven-term remote start
raven-term pairing --qr

Scan the new code on the phone. With the Mac awake, turn off Wi-Fi on the phone and connect over cellular to check the relay path. The phone’s TLS session remains pinned to the Mac’s certificate; the relay forwards encrypted bytes and cannot read terminal traffic.

Run the relay in raven-hub

For service operators: create a private token file on the server and give the same token to the Mac owner. A current raven-hub build can serve the phone relay by itself:

raven-hub --role relay --relay-listen 0.0.0.0:8443 \
  --relay-tenant office=/run/secrets/office-relay-token

To run it alongside Teams, add the same relay flags to --role hub or --role all. Token files must already exist and contain a nonempty secret. Tenant names must be unique lowercase DNS labels; tenant changes require a restart.

Point office.relay.example.com at the server and open TCP port 8443. For several Macs, add one --relay-tenant per Mac and point each tenant hostname (or wildcard DNS) at the same relay. The first hostname label selects the Mac when several tenants are configured.

Use raw TCP passthrough at the load balancer. Do not terminate phone TLS there: it must reach the Mac. Route all relay connections to one relay process; independent replicas cannot pair the Mac’s control and data connections with the phone’s connection. These flags configure a self-hosted relay. Raven’s hosted relay uses signed-in device identities rather than these static tenant secrets.

If the connection fails

• On the Mac, run raven-term remote status to confirm the listener is running. Wake the Mac and check iOS Local Network permission for a Wi-Fi connection.
• Open Connection Settings in RavenRemote and inspect the connection log. Check the host, port, TLS setting, and pairing details; TLS uses 18486 directly or your operator’s relay port.
• If the Mac’s configuration sets [remote] bind to 127.0.0.1, direct Wi-Fi connections cannot reach it. Remove that override or bind to the Mac’s LAN address, then restart the listener. An unset bind listens on all interfaces while retaining the peer filters.
• If a relay works at home but fails on cellular, verify the public relay hostname and port, the matching Mac/server relay tokens, and the tenant name. Pair again if the relay was added after your last scan.
• If the Mac’s certificate or pairing token has changed, pair again with a fresh code from that Mac. Keep certificate verification enabled.

To stop remote access, choose Stop Remote Listenerin the palette or run raven-term remote stop on the Mac.