02 / Remote access
Access Pi Coding Agent remotely
Pix connects your iPhone to Pi on your Mac or Linux machine using the simplest available path: a direct LAN connection nearby or an outbound encrypted relay when the devices are on different networks.
Pix appdirect TCPMac / Linux
Pix Host + Pi
Pix appencrypted → relay → encryptedMac / Linux
Pix Host + Pi
How Pix connects to Pi remotely
Both transport paths carry the same encrypted Pix channel after the connection is established. The host and client authenticate the channel; the relay only helps endpoints find and reach each other when a direct path is unavailable.
On the same network: direct connection
When your iPhone and computer share a network, Bonjour discovers the Pix host and the client connects directly over TCP. The relay is not involved in this path, but device pairing and workspace authorization still apply.
- Keep the iPhone and host on the same network.
- Choose the nearby host discovered by Bonjour.
- Compare the pairing code and approve the request on the host.
Away from home: encrypted relay
For different networks, Pix Host opens an outbound WebSocket connection to the configured relay. The relay authenticates channel roles and forwards opaque encrypted frames; it cannot run Pi or terminate the secure channel.
Review pairing expiry, revoke controls, and relay configuration in the remote access guide.
What can the relay see?
| Relay can | Relay cannot |
|---|---|
| Forward encrypted frames | Read prompts or model output |
| Authenticate channel roles | Read repository contents or code |
| Enforce connection and size limits | Browse the host filesystem |
| Route the client to the host | Run Pi or create a session |
| Observe transport metadata needed to route | Queue, persist, or replay application payloads |
What happens when the connection drops?
A relay or network failure changes reachability, not the local runtime. Pi and its session continue running on the host; Pix can reconnect when the phone and host can reach each other again.
Learn how to return to the same native session in the session continuity guide.
Can I self-host the relay?
Yes. The public relay is a Cloudflare Worker under the repository’s relay/ directory. Deploy your own Worker, configure its wss:// endpoint in Pix, and keep the same content-blind encrypted-channel contract.
Follow the deployment steps in the self-hosted relay documentation.
Questions
Common questions
Which connection does Pix use?
Pix uses a direct Bonjour-discovered TCP connection when the iPhone and host share a network. It uses the configured encrypted relay when they are on different networks.
Do I need to open a port on my router?
No. With relay access, Pix Host makes an outbound WebSocket connection, so you do not need to expose an inbound router port. Direct LAN access stays inside your local network.
Can the relay read my prompts or code?
No. The relay forwards opaque encrypted frames and does not terminate the Pix secure channel or store application payloads.
What happens if the relay goes offline?
The phone loses reachability until the connection returns, but Pi and the local session continue running on the host.
Can I self-host a Pix relay?
Yes. Deploy the public Cloudflare Worker in the relay/ directory and configure its wss:// endpoint with Pix. Self-hosting does not change the hosted relay.
How does remote pairing work?
The host creates a single-use QR pairing offer. The offer and short pairing channel expire after two minutes; compare the six-digit code on both devices and approve the request on the host.