How it works
The architecture that keeps terminal data off the server.
Porthole is built around one idea: the server should never see your terminal. Everything below follows from that.
The pieces
- Agent — the
portholebinary on your machine. It opens a PTY (a real shell), and speaks WebRTC to the viewer. - Signaling server — a small, stateless service that introduces two peers to each other. It holds sessions in memory only; there is no database.
- Viewer — the browser on the other end. No install, no extension.
The handshake
WebRTC peers can't find each other on their own — they need a broker to swap connection details. That is the signaling server's entire job:
- The agent registers a session and gets a short token (
p3rx-9kma). - The viewer opens the link and joins that session.
- The two exchange SDP offers/answers and ICE candidates through the server.
- A direct, encrypted WebRTC DataChannel opens between them.
From step 4 on, the server is out of the loop. Terminal output and your viewer's keystrokes travel directly between the two peers.
The signaling server only ever relays the metadata needed to connect. It never sees a single byte of terminal output or input.
Why it's private
- Direct path — once connected, there is no server in the middle to log, store, or leak terminal data.
- Encrypted in transit — WebRTC DataChannels are encrypted with DTLS by default.
- Enforced at the source — read-only and password rules are applied by the agent on your machine, so a tampered viewer can't bypass them.
Ordered and reliable
The DataChannel is configured as ordered and reliable (TCP-like). Keystrokes and output arrive in order, with nothing dropped — exactly what a terminal needs.
If a direct connection can't be established (some strict NATs/firewalls), WebRTC falls back to a TURN relay to keep the session working. The relay forwards encrypted packets; it still cannot read your terminal.