← Back to pmux.io

How Pocketmux keeps your terminal private

Remote tmux access means terminal data leaves your machine — so the security model matters more than the marketing. This page explains exactly how Pocketmux protects that data, in enough detail to verify the claims against the open-source code.

Identity & authentication

Each device — your computer's agent and your phone — generates an Ed25519 keypair on first run. Authentication is performed by signing a server challenge with the private key. There are no passwords, no OAuth, and no email accounts to phish or leak.

  • • Agent: keypair stored in ~/.config/pmux/keys/
  • • Mobile: keypair stored in the iOS Keychain / Android Keystore, hardware-backed where available — device keys never leave secure storage

Device pairing

Pairing is a one-time operation inspired by Signal's device linking. Running pmux pair shows a QR code containing a one-time pairing code and an ephemeral X25519 public key. Your phone scans it, both sides perform an X25519 key exchange, and the resulting shared secret is stored only on the two devices. The shared secret is never sent to or stored on the server. Each host pairs with exactly one mobile device; re-pairing replaces the old pairing and notifies the previous device.

Encryption in transit

  • • Signaling: WSS (TLS) to Cloudflare — connection setup only, never terminal content
  • • Terminal data: WebRTC DataChannels with DTLS encryption, end-to-end between your devices — the server is not in the data path and cannot decrypt it
  • • TURN fallback: when a direct peer-to-peer connection isn't possible, traffic relays through TURN — but DTLS encryption is maintained end-to-end, so the relay sees encrypted bytes only

The server is untrusted by design

The threat model treats the signaling server as an untrusted relay. At every connect, before any request is processed, the connecting phone must prove possession of the X25519 pairing secret: the agent sends a random challenge over the encrypted DataChannel and the phone answers with an HMAC-SHA256 over it, verified in constant time. Because the server never holds the shared secret and is never in the DataChannel path, even a fully compromised signaling server cannot impersonate your phone. Invalid or missing proof closes the connection — the agent fails closed.

What the server never knows

  • •How many tmux sessions, windows, or panes exist on any machine
  • •What commands are running
  • •What you type
  • •What terminal output looks like
  • •When you attach to or detach from panes
  • •The X25519 shared secret between paired devices
  • •Any terminal content whatsoever

What the server does know

Zero-knowledge claims should be specific, so here is the complete list:

  • •Device public keys (Ed25519)
  • •Which host is paired with which mobile device
  • •Whether an agent is currently online
  • •Connection metadata during signaling (IP addresses, timing)

On-device protections

The mobile app ships with a biometric lock (on by default), a 5-minute auto-lock timeout, automatic clipboard clearing 30 seconds after copying from the terminal, and an option to disable the TURN relay entirely for strict peer-to-peer-only operation.

Verify it yourself

The CLI, agent, signaling server, and wire protocol are open source under the MIT license — the guarantees above are enforced in code you can read, not just policy. See also our Privacy Policy.

Reporting a vulnerability

Found a security issue? Email [email protected] and we'll respond as quickly as we can. Please give us a reasonable window to fix the issue before public disclosure. Our disclosure details are also published at /.well-known/security.txt.