Skip to main content
Wrapper treats terminal content as sensitive. A session is local and owner-only until its host explicitly shares it.

​
Access requirements

​
Local attach

  • The WebSocket listens only on 127.0.0.1.
  • Every host generates a random 256-bit local token.
  • The token is stored in the owner’s protected session registry.
  • A local connection without the token is rejected before reaching the PTY.
  • Released binaries authorize local attach with the loopback token. Convex is not contacted until the host shares.
Processes running as the same operating-system account, and root or administrator, remain inside the local trust boundary.

​
Relay attach

  • Every user authenticates with Better Auth.
  • The owner can join their own active shared session without a share code.
  • A non-owner needs both the session id and share code.
  • Share codes are stored only as hashes.
  • Failed attempts are limited per account, per hashed target bucket, and globally without revealing whether the target exists.
  • Relay tickets are random, hashed at rest, short-lived, and single-use.
  • Ticket consumption rechecks session state, so unsharing invalidates unused viewer tickets.
Unknown, unshared, missing-code, and wrong-code sessions return the same denial shape so session ids cannot be enumerated from error messages.

​
Terminal-data paths

​
Unshared

Input, output, and session metadata stay on the host machine. Convex is not contacted until you share.

​
Direct WebRTC

The viewer and host negotiate a DTLS-encrypted data channel through authenticated relay signaling. Viewer input prefers the direct channel. WebRTC exposes each peer’s IP address to the other peer and uses public STUN servers for discovery:
  • stun.l.google.com:19302
  • global.stun.twilio.com:3478
The host currently keeps relay output available for fallback and mixed viewers. Wrapper therefore does not claim that the hosted relay is zero knowledge.

​
Relay fallback

When P2P is unavailable or disabled, terminal traffic travels through the Fly.io relay over WSS. TLS protects traffic in transit, but relay infrastructure processes plaintext after TLS termination to route it. The application does not intentionally persist terminal payloads. Use WRAPPER_P2P=0 to force relay-only behavior. Do not share a session whose content you are not willing to send through the configured relay.

​
Shared sessions

People you invite see the screen. They cannot type unless you allow it with Ctrl+\ then w, or by starting with wrapper share --writable. You always type, including from your phone. Share codes are capabilities: give them only to people you trust, and press Ctrl+\ then u when you are done. Interactive CLI attach asks for the share code in a hidden prompt. --code is reserved for automation because command-line arguments can be visible in shell history and process listings. Attention alerts to the owner’s phone name the session only. They never include terminal output, commands, paths, or credentials. Disable them with WRAPPER_NOTIFY=0.

​
Payload and abuse protection

  • Raw wire frames are capped before JSON parsing.
  • Terminal input, output, and signaling payloads have explicit size limits.
  • The relay caps messages buffered before authorization.
  • Peer ids are assigned by the relay and cannot be spoofed by clients.
  • Messages with a different session id are rejected.

​
Local credentials

The CLI stores its Better Auth session token, local attach token, and logs in user-protected files. Run wrapper auth logout on a device whose credentials may be exposed. Malware running as your operating-system user can access files that you can access; Wrapper cannot remove that operating-system trust boundary.

​
Telemetry

Anonymous CLI telemetry is disabled by default. Enable it explicitly with:
The website uses Vercel Web Analytics for anonymized page views. It does not use cookies. PostHog is not used on the website while NEXT_PUBLIC_POSTHOG_KEY is empty. Telemetry must never include terminal input or output, share codes, relay tickets, or authentication tokens.

​
Report a vulnerability

Do not publish suspected vulnerabilities. Follow the hosted security-reporting instructions or the repository’s branch-independent security policy. Reports can be sent to [email protected] or submitted as a private GitHub security advisory.
Last modified on September 14, 2026