Security & Architecture

PocketShell prefers authenticated WebRTC data channels between your phone and host. Direct and TURN-relayed WebRTC traffic is protected by DTLS end to end; a TURN provider forwards encrypted packets and can observe endpoint IPs, timing and volume. The backend relays signed SDP and ICE setup messages.

What our backend can see

Account email, host metadata, session lifecycle records, alert rules, push tokens, audit events, and lightweight background metric snapshots used for presence, alerts and history. Selected numeric metrics are persisted; process tables, command lines and logged-in users are not included in those background snapshots.

WebSocket fallback

While WebRTC is starting or unavailable, terminal and coding-agent traffic may use PocketShell's signaling WebSocket. Those frames are protected by WSS/TLS but are not end-to-end encrypted: PocketShell's application servers can read them while relaying them. The current app does not reliably badge terminal or agent fallback.

Identity and encryption

Both ends hold Ed25519 keypairs. Pairing pins device identities with a one-time QR flow. WebRTC data channels run DTLS, with the peer-certificate fingerprint bound into an Ed25519-signed SDP transcript. Signaling-based file operations normally add ChaCha20-Poly1305 using an ephemeral X25519 secret and HKDF-SHA256. If file key exchange fails, the current client can fall back to WSS/TLS; paths, listings and small file operations can then be server-readable. Large streaming transfers require WebRTC.

Verify it yourself

The host agent is open source (Apache-2.0) at github.com/yashagldit/PocketShell. The install script verifies SHA-256 checksums and a Sigstore signature pinned to the release workflow. Removal is one command: pocketshell uninstall.

Honest limits

A device you approve with shell permission has the same power as you at the terminal. Availability depends on our backend. New setup from a revoked device is blocked when revocation is committed; an open direct channel closes after the host's next trust sync, five minutes by default. TURN exposes connection metadata but not DTLS payloads; WebSocket fallbacks expose the payloads described above. No independent third-party audit has been commissioned.

Report vulnerabilities to support@pocketshell.app with "Security" in the subject.

Enable JavaScript for the full document.