--- title: "How PiperMesh Works: Direct on LAN, Encrypted Everywhere Else" description: "PiperMesh tries three paths to connect your devices: direct on LAN, NAT-traversed peer-to-peer, then encrypted relay. All three use Noise encryption end-to-end." date: 2026-05-03 author: "Ben Racicot" tags: ["PiperMesh", "Privacy", "Networking", "End-to-end Encryption", "macOS", "iOS", "Cross-platform"] type: "article" canonical: "https://modelpiper.com/blog/how-pipermesh-works/" --- # How PiperMesh Works: Direct on LAN, Encrypted Everywhere Else > PiperMesh tries three paths to connect your devices: direct on LAN, NAT-traversed peer-to-peer, then encrypted relay. All three use Noise encryption end-to-end. ## TL;DR PiperMesh is the network layer that lets your phone, watch, and PC reach the ToolPiper running on your Mac. It tries three connection paths in order - direct on the local network, NAT-traversed peer-to-peer, and an encrypted relay through api.modelpiper.com - and uses the first that works. Every path is wrapped in Noise (the protocol behind WireGuard and Signal), so even on the relay path, our server can only see ciphertext. The relay exists for the cases that matter: cellular networks, corporate wifi, strict NATs. It's never the only option, and it's never the cleartext option. You have a Mac at home running ToolPiper. You have an iPhone in your pocket on cellular. You'd like the phone to reach the Mac. That sentence sounds simple. It's not. The two devices are on different networks, behind different NATs, with different public IPs. Neither one can address the other directly. There's no DNS entry pointing your phone at your Mac. Your home router doesn't accept incoming connections on whatever port ToolPiper happens to be listening on. This is the problem PiperMesh solves. The same problem Tailscale solves for VPN, that Signal solves for messaging, that FaceTime solves for video. Same shape, different domain. ## What is PiperMesh? PiperMesh is the network layer inside ToolPiper that lets your other devices - iPhone, iPad, Apple Watch, Windows or Linux PC - reach your Mac wherever it is. It uses a coordination server to help peers find each other, then connects them directly when possible and falls back to an encrypted relay when not. All traffic is end-to-end encrypted with the Noise Protocol Framework regardless of which path it takes. The mental model that's easiest to hold: a phone book that knows where to find your devices, plus a fallback pipe that can carry encrypted bytes between them when the phone book isn't enough. The phone book is what most of the work goes into. The pipe is what makes the privacy story honest. ## Layer 1: The phone book The coordination layer lives at `api.modelpiper.com/v1/mesh`. Its job is small and specific. It knows: - Which devices belong to your account - Each device's public key - Each device's last-known network candidates - LAN address, public IP for hole-punching, push token for waking it up if it's sleeping It does not know what you ask the AI, what the AI replies, what's on your clipboard, or what's in your snippets. None of that data ever reaches it because the data plane doesn't run through the coordination layer at all. This is the fundamental architectural choice that distinguishes a mesh from a cloud service. iMessage works the same way. Signal works the same way. The coordination layer is also stateless HTTP plus push notifications. There's no persistent socket, no heartbeat, no idle keep-alive. When a peer needs to be reached and isn't responding, the API sends a single APNs or FCM push to wake it. The woken device posts updated candidates and the requester retries. Same pattern as offline iMessage delivery. ## Layer 2: Three paths to a peer Once you know where a peer might be, you still have to actually reach it. PiperMesh tries three approaches, in order, and uses the first that succeeds. The application layer never sees the difference. ### Path 1: LAN direct Both devices on the same network. Your iPhone is on home wifi, your Mac is on home wifi, both are visible to each other on `192.168.x.x`. The client resolves `studio.local` via Bonjour (the same mDNS protocol AirDrop and Handoff use) and connects directly. No NAT, no STUN, no relay. Latency is whatever your wifi can do, usually under 10ms. This is the fastest path and it's the path most people use most of the time. If you're at home with all your devices, this is what's running. ### Path 2: NAT-traversed peer-to-peer Different networks. Your phone is on cellular, your Mac is on home wifi. Neither device can address the other directly because both are behind NATs that drop unsolicited inbound packets. The trick is a coordinated UDP probe. Each device queries a STUN server to learn its public IP and port. Both devices post those candidates to the coordination server. Then both sides simultaneously fire UDP packets at each other's public addresses. The first packet from your phone punches a hole in your phone's NAT, and the first packet from your Mac punches a hole in your home router's NAT. After that, packets flow. This is called DISCO, the same technique Tailscale uses. We deliberately don't use full WebRTC ICE - it carries a SDP state machine that's overkill for our case, and it depends on STUN servers we don't control. PiperMesh ships its own minimal candidate gathering. Works for about 85-90% of NAT configurations in practice. ### Path 3: Encrypted relay Strict NATs that refuse to participate in hole-punching. Corporate networks with deep packet inspection. Some mobile carriers that aggressively rewrite traffic. There's a non-zero chance Path 2 just doesn't work, and "sorry, your phone can't reach your Mac today" is not an acceptable answer. So both peers connect to `api.modelpiper.com/v1/mesh/relay//stream`. The server pipes raw bytes between the two authenticated connections. It verifies that both ends belong to the same user account before opening the pipe. It rate-limits sessions and tears them down after four hours of idle. The thing the server is piping is Noise ciphertext. It cannot inspect the payload. We'll come back to that in Layer 3 because it's the part most people want to verify. ### Relay-first, then upgrade One detail that's worth its own paragraph: when a connection starts, PiperMesh connects via the relay _immediately_. It doesn't wait for hole-punching to succeed before sending the first byte. Both peers also start probing for a direct path in parallel. When a direct path is confirmed, the connection migrates transparently and the relay session closes. This is the Tailscale model and it produces noticeably better UX than the alternative. Hole-punching can take a couple of seconds. Voice chat can't tolerate a 2-second cold start. Starting on the relay and upgrading silently means the first byte goes out within tens of milliseconds, and the connection gets faster in the background. ## Layer 3: What the relay can actually see The PiperMesh relay can see metadata - which two of your devices are talking, when, how much data, which IP they came from. It cannot see the contents of any message because all device-to-device traffic is wrapped in Noise Protocol Framework encryption end-to-end. The relay is a pipe for ciphertext, not a server that processes your data. This is the part that distinguishes a relay from a cloud service. A cloud chat service decrypts your message on its servers, runs the AI, encrypts the response, sends it back. A relay never decrypts anything. It moves bytes from one side to the other. Noise is the cryptographic foundation behind WireGuard, Signal, and WhatsApp. It's not a custom protocol we wrote. The specific patterns we use: - **Initial pairing** uses `Noise_XX_25519_ChaChaPoly_BLAKE2s`. Three-message mutual authentication with identity hiding. Neither device's identity key is visible to a passive observer during the handshake. - **All subsequent connections** use `Noise_IK_25519_ChaChaPoly_BLAKE2s`. One round-trip, both sides already know the other's static public key. This is the same handshake WireGuard uses. - **Session keys are ephemeral.** When a connection drops, the key is gone. A relay session captured today and decrypted tomorrow with a stolen identity key still cannot be read. This is forward secrecy, automatic. - **Long-lived sessions rotate keys** every 50 epochs or 10 minutes, whichever comes first. Voice chat re-keys multiple times during a single conversation. On Apple devices, your identity key lives in the Secure Enclave. The private key is hardware-bound and not exportable, even to the OS, even on a jailbroken device. On Windows the key sits in DPAPI-protected storage. On Linux, libsecret. On Android, Keystore. The wire protocol carries a `keyType` field so platforms interoperate cleanly. ## What if you don't trust our coordination server? You don't have to use it. PiperMesh has a no-account power-user mode that works entirely offline from `api.modelpiper.com`. The Mac generates a QR code that encodes its LAN address, a bearer token, and the SHA-256 hash of its TLS certificate's public key. You scan the QR code with your phone. The phone connects directly over the local network, pins the certificate hash from the QR, and completes the Noise pairing handshake. The coordination server is never involved. This is slower to set up - you have to be on the same network, you have to scan a QR code per device - but it's a real option. It's the HomeKit model: the QR code is the out-of-band trust anchor. Useful for users who refuse cloud coordination on principle, or for environments where the coordination server isn't reachable. The trade-off is feature surface. No-account mode is LAN-only. No NAT traversal. No relay. If your phone leaves the house, you lose the connection until you're back on the same network. ## How does this compare to Tailscale or iCloud? The closest analogues are Tailscale (for the network layer) and iMessage (for the privacy posture). They solve adjacent problems with similar architectures. Tailscale is general-purpose VPN over WireGuard. It's excellent at what it does. PiperMesh isn't trying to replace Tailscale, and we recommend it to users who want a full WireGuard mesh for arbitrary services. PiperMesh is purpose-built for ToolPiper - it knows about pairing flows, push wake, mobile scope filtering, key rotation tied to device replacement. Things a general-purpose VPN doesn't handle natively. iMessage is the privacy comparison most users will recognize. Apple's coordination servers route messages between devices. They see who is talking to whom, when, how much data. They cannot see what you said, because the message body is encrypted with keys only your devices hold. PiperMesh inherits the same posture for AI inference. Apple has stated this publicly in court filings and security white papers, and the architecture has held up under independent review. Same shape here, smaller scale. The contrast that matters is with cloud AI products. ChatGPT, Claude, Gemini, and similar services see every message you send because their servers do the inference. That's not a policy choice they could change - it's an architectural fact of running models in the cloud. PiperMesh keeps inference local on your Mac and uses encryption to keep transit private. The relay never has the keys to decrypt anything. ## Honest limitations This isn't a perfect system. A few things worth being upfront about. **The relay can be congested.** If a lot of users are on cellular and falling back to relay simultaneously, throughput per session drops. We rate-limit and impose session caps to prevent one user from monopolizing the resource pool, which means a heavy file transfer might be capped at the relay's per-user budget. Direct paths don't have this constraint. **Latency on the relay is worse.** Round-trip through `api.modelpiper.com` adds whatever the network distance to our infrastructure is, on top of the actual peer-to-peer latency. For chat and voice, this is usually fine. For real-time interactive tasks like cursor sharing, direct paths are noticeably better. **Metadata isn't free.** The coordination server logs that your Mac came online at this time, that your phone connected to it, that they exchanged some data. We don't log message contents because we can't, but the timing and volume metadata exists in our infrastructure. Standard for any networked service. If your threat model can't tolerate this, the no-account QR mode is the answer. **Post-quantum is a moving target.** When both devices run macOS 26 or iOS 26, session keys upgrade to X-Wing - a hybrid of X25519 and ML-KEM-1024 that an attacker would have to break both classical and post-quantum primitives to read. Older OSes fall back to classical Noise. We'll keep tracking the post-quantum standardization and ship upgrades as the cryptographic primitives mature. ## Try it PiperMesh is the network layer behind PiperMesh, the cross-device add-on for ToolPiper. It's a slot-based add-on that stacks on any tier including Free: $7/month for 4 slots or $19.99/month for 20 slots (Family). Unlocks MobilePiper on every platform: iPhone, iPad, Apple Watch, Windows, Linux. The Mac runs the AI. Everything else just talks to it. Download ToolPiper at [modelpiper.com](https://modelpiper.com). _Related: [Is ToolPiper Safe?](/blog/is-toolpiper-safe) - what stays local and how to verify it. [Why Voice AI Should Stay Local](/blog/why-voice-ai-should-stay-local) - the privacy argument for biometric data._ ## FAQ ### Does PiperMesh send my AI conversations through your servers? Only when no direct path is available. PiperMesh tries direct LAN connection first, then NAT-traversed peer-to-peer, then falls back to an encrypted relay through api.modelpiper.com. When the relay path is in use, our servers can see metadata (which devices are talking, when, how much data) but not message content - all traffic is encrypted end-to-end with the Noise Protocol Framework. The relay is a pipe for ciphertext, not a server that decrypts your data. ### How is PiperMesh different from sending data to a cloud AI service? Cloud AI services run inference on their servers, so they must be able to read your prompt. PiperMesh runs inference on your Mac. The mesh layer only moves encrypted bytes between your devices. Even when traffic goes through our relay, we can never read it because we don't hold the encryption keys - those live in your devices' Secure Enclave (Apple) or platform keystore (Windows, Linux, Android). ### Can I use PiperMesh without an account? Yes, in LAN-only mode via QR pairing. The Mac generates a QR code containing its LAN address, a bearer token, and TLS certificate hash. You scan it with your phone, which pins the cert and completes a Noise pairing handshake directly over your local network. The coordination server is never contacted. The trade-off is that LAN-only mode requires both devices to be on the same network - no NAT traversal, no relay, no cellular access. ### Why do you have a relay at all if direct connections work most of the time? Strict NATs, corporate networks, and some mobile carriers prevent peer-to-peer hole-punching from succeeding. Without a relay, those configurations would simply fail. The relay also lets connections start sending data instantly while a direct path is still being established in the background, which removes the cold-start delay you'd otherwise see when opening a chat or voice session. About 10-15% of NAT configurations need the relay path, and 100% of new connections benefit from the instant-start behavior. ### What encryption does PiperMesh use? The Noise Protocol Framework, the same cryptographic foundation behind WireGuard and Signal. Initial pairing uses Noise\_XX with mutual authentication and identity hiding. All subsequent connections use Noise\_IK for one-round-trip re-authentication. Session keys are ephemeral and rotate every 10 minutes or 50 epochs. On Apple devices, identity keys are hardware-bound in the Secure Enclave and cannot be exported even by the OS. On macOS 26 and iOS 26, session key derivation upgrades to X-Wing, a post-quantum hybrid of X25519 and ML-KEM-1024. ### What information does the coordination server actually log? Device registration data (your account ID, each device's public key, each device's name and type), reachability metadata (last seen timestamp, network candidates), push tokens for wake notifications, and relay session metadata when relay paths are active (which two devices, when, how long, how much data). It never sees message contents, AI prompts, AI responses, clipboard data, or snippets - those never travel through the coordination layer. This is the same metadata posture as iMessage and Signal.