@piyushagade/pearssh-bridge 🍐⚡

PearSSH Local CLI Bridge Agent — Seamlessly connect the PearSSH Web Client to private Tailscale mesh hosts (100.x.x.x / *.ts.net), VPNs, and local network machines (192.168.x.x).

💡 What is PearSSH Bridge?

Modern web browsers cannot establish raw TCP socket connections (such as SSH on port 22 or VNC on port 5900) directly to private Tailnet IP addresses due to browser sandbox security policies.

PearSSH Bridge runs locally on your computer as a lightweight, zero-dependency Node.js CLI daemon. It opens a local WebSocket endpoint (ws://localhost:4000) that proxies encrypted WebSocket messages from the PearSSH web app into direct SSH, SFTP, and VNC streams reaching any host in your local network or Tailscale mesh.

┌────────────────────────┐         WebSocket          ┌───────────────────────────┐         SSH / SFTP          ┌───────────────────────────┐
│  PearSSH Web Frontend   │ ────────────────────────> │   pearssh-bridge Agent    │ ──────────────────────────> │   Tailscale / LAN Host    │
│ (https://.../pearssh)  │   ws://localhost:4000     │  (Runs on your computer)  │   100.x.x.x or 192.168.x.x   │ (Port 22 / 5900)          │
└────────────────────────┘                            └───────────────────────────┘                             └───────────────────────────┘

✨ Features

• ⚡ Instant Zero-Install Execution: Launch instantly with Node's built-in npx command.
• 🌐 Bypasses Network & Tailnet Restrictions: Routes SSH/SFTP/VNC traffic into private Tailnets (100.64.0.0/10) and internal subnet IPs without configuring complex relays.
• 📂 SFTP Archive Streaming: Real-time remote file explorer support, live file editing, and dynamic ZIP/TAR directory archiving.
• 🖥️ Remote VNC Desktop Tunneling: Direct TCP socket tunneling for graphical desktops streaming over noVNC.
• 🔄 Session Resilience: Built-in connection pool for seamless session re-attachment across network drops or page reloads.
• 📊 Real-time System Metrics: Live CPU, RAM, OS, and uptime diagnostic reporting for monitored hosts.
• 🔒 Zero-Knowledge Security: Credentials and private keys pass through local memory only and are never transmitted to external third-party servers.

🚀 Quick Start

Option 1: Instant Launch (Recommended)

No installation required! Run directly using npx:

npx @piyushagade/pearssh-bridge@latest

Option 2: Custom Port

If port 4000 is already in use on your machine, specify a custom port:

npx @piyushagade/pearssh-bridge@latest --port 5000

🔄 Run as a Background Daemon (Auto-Start on Reboot)

To keep pearssh-bridge running silently in the background and ensure it automatically restarts on system reboot (Linux, macOS, Windows):

# 1. Install globally with PM2
npm install -g @piyushagade/pearssh-bridge@latest pm2

# 2. Start the bridge under PM2 manager
pm2 start @piyushagade/pearssh-bridge --name pearssh-bridge

# 3. Save process list & generate auto-start script
pm2 startup
pm2 save

⚙️ CLI Options

| Flag | Description | Default | |---|---|---| | --port <number> | Port number for the local WebSocket bridge server | 4000 | | --help | Display CLI options and usage information | - |

🔒 Security & Credential Privacy

• Local Memory Only: All SSH authentications (passwords, private keys, SSH agent sockets) are processed in memory by the local bridge daemon.
• No Third-Party Analytics: No telemetry, tracking, or remote key logging.
• Encrypted Local Transport: WebSockets communicate strictly over local interface bindings (localhost).

📄 License

MIT License © 2026 Piyush Agade.