A browser extension + native host that brings Holesail P2P tunneling into standard desktop browsers (Chrome, Edge, Firefox) without forking the browser. Open hs:// URLs as if they were normal HTTPS sites, expose local services as P2P tunnels, SSH into remote machines, and connect to remote desktops — all through the browser.

What It Does

Browse hs:// URLs — paste any Holesail key and navigate to it like a normal HTTPS site
Expose local services — share a local port as an hs:// URL that anyone with the key can reach
Service tunnels — forward a remote Holesail peer to a local TCP port (databases, game servers, etc.)
SSH in the browser — full xterm.js terminal over a Holesail tunnel, no port forwarding needed
Remote Desktop — VNC and RDP sessions over Holesail tunnels, rendered in the browser
Automatic backups — scheduled tar.gz backups of all state and certificates with configurable retention

How It Works

Browser Extension (MV3)
    │ Chrome Native Messaging (stdin/stdout)
    ▼
Native Host (Bare runtime)
    ├── Holesail tunnel manager
    ├── SSH session manager      (ports 20000–21999)
    ├── Remote Desktop manager   (ports 22000–23999)
    ├── Backup manager           (tar.gz, configurable retention)
    ├── HTTPS proxy  (127.0.0.1:8443)  ← TLS termination, *.hole.sail cert
    └── CONNECT proxy (127.0.0.1:8442) ← PAC script target

When you navigate to myapp.hole.sail, the extension's PAC script routes the request through the local CONNECT proxy → HTTPS proxy → Holesail tunnel → remote peer. The browser sees a valid HTTPS response with no certificate errors (once the CA is installed).

All state — tunnels, settings, SSH connections, RDP connections — is stored in a single state.json file owned by the native host.

Installation

Prerequisites

Bare runtime installed and on your PATH
Chrome 88+, Edge, or Firefox 79+

macOS / Linux

git clone https://github.com/holesail/holesail-browser.git
cd holesail-browser
./scripts/install.sh

Windows

git clone https://github.com/holesail/holesail-browser.git
cd holesail-browser
.\scripts\install.ps1

The installer builds the native host binary, registers the native messaging manifest, and packages the extension.

Load the Extension

Chrome / Edge:

Go to chrome://extensions
Enable Developer mode
Click Load unpacked → select the extension/ folder

Firefox:

Go to about:debugging#/runtime/this-firefox
Click Load Temporary Add-on → select extension/manifest.json

Install the CA Certificate

Open the Holesail Dashboard (click the extension icon) → go to Proxy & CA → click Install CA. This installs the local Holesail Browser CA root certificate so *.hole.sail sites load without certificate warnings.

Quick Start

Browse an `hs://` URL

Click the extension icon to open the Dashboard
Go to Virtual Hosts → paste an hs:// key → click Add
Navigate to the assigned *.hole.sail hostname in your browser

Expose a Local Service

Dashboard → Servers → enter your local port → select TCP or UDP → click Start
Copy the generated hs:// URL and share it

SSH into a Remote Machine

Dashboard → SSH → click Add Connection
Enter the hs:// key, username, and an optional label
Click Connect — an xterm.js terminal opens in the dashboard

Connect to a Remote Desktop

Dashboard → Remote Desktop → click Add Connection
Enter the hs:// key, select VNC or RDP, configure port and credentials
Click Connect — the viewer opens in the dashboard

Take a Backup

Dashboard → Backups → click Take Backup
Backups are stored as tar.gz archives including all state and certificates
Configure retention in Settings → Backup Retention (default: 5)

Architecture

See docs/ARCHITECTURE.md for the full system diagram and message flow.

Documentation

Document	Description
docs/ARCHITECTURE.md	System architecture, component breakdown, message flow
docs/INSTALLATION.md	Detailed install guide for all platforms
docs/TUNNELING.md	How `hs://` browsing, virtual hosts, and service tunnels work
docs/SSH.md	SSH tunnel feature
docs/REMOTE-DESKTOP.md	VNC and RDP remote desktop feature
docs/BACKUP.md	Backup and restore feature
docs/SECURITY.md	CA trust model, encryption, threat mitigations
docs/NATIVE-HOST.md	Native messaging protocol and host command reference

Technologies

Technology	Role
Holesail	P2P TCP tunneling
Bare	Lightweight JS runtime for the native host
node-forge	TLS/PKI for CA and certificate generation
xterm.js	Terminal emulator for SSH sessions
noVNC	Browser-side VNC client (RFB protocol)
node-rdpjs-2	Server-side RDP client for Remote Desktop

Build Commands

npm run build:host          # Generate bare launcher script (requires bare on PATH)
npm run build               # Same as build:host
npm run pack                # Package extension as .zip / .xpi

# Standalone distributable binaries (no bare runtime required at runtime)
npm run build:dist          # Build for current host only
npm run build:dist:all      # Build for all platforms (mac + linux + windows)
npm run build:dist:mac      # darwin-arm64 + darwin-x64
npm run build:dist:linux    # linux-arm64 + linux-x64
npm run build:dist:win      # win32-x64
npm run build:dist:package  # All platforms + create .zip archives

Distributable binaries are written to releases/. They are self-contained — no bare runtime, no node_modules, no dependencies needed on the target machine.

File Layout

holesail-browser/
├── extension/                  # Browser extension (Manifest V3)
│   ├── manifest.json
│   ├── background.js           # Service worker, native messaging, PAC proxy
│   ├── content.js              # Content script, event relay
│   ├── dashboard.html/js       # Management UI (10 pages)
│   └── vendor/                 # Bundled xterm.js, noVNC
├── native-host/                # Native messaging host (Bare runtime)
│   ├── index.mjs               # Entry point
│   ├── host.js                 # Command handler (30+ commands)
│   ├── holesail-manager.js     # Tunnel lifecycle + state.json persistence
│   ├── https-proxy.js          # HTTPS reverse proxy (port 8443)
│   ├── connect-proxy.js        # HTTP CONNECT proxy (port 8442)
│   ├── certificate-authority.js
│   ├── ssh-manager.js          # SSH sessions (ports 20000–21999)
│   ├── rdp-manager.js          # Remote Desktop sessions (ports 22000–23999)
│   ├── backup-manager.js       # tar.gz backup/restore
│   └── holesail-browser-storage/
│       ├── state.json          # All persistent state
│       └── backups/            # Backup archives
├── holesail-browser-certs/     # Generated CA and domain certs (also backed up)
├── scripts/                    # Install and build scripts
└── com.holesail.browser.json   # Native messaging manifest

Troubleshooting

"Native host has exited" — Re-run ./scripts/install.sh. The manifest needs absolute paths to bare.

"Access to the specified native messaging host is forbidden" — Extension ID mismatch. Run ./scripts/update-native-manifest-extension-id.sh YOUR_EXTENSION_ID.

*.hole.sail sites show certificate errors — Install the CA via Dashboard → Proxy & CA → Install CA.

PAC proxy not active — Another extension may be controlling proxy settings. Check Dashboard → Proxy & CA for proxy status.

VNC/RDP "bare-tcp not available" — Rebuild the native host: npm run build:host.

Backup "tar failed" — Ensure tar is available on PATH (standard on macOS/Linux; install via WSL or Git Bash on Windows).

Security

The native host runs with your user privileges. Only install from sources you trust.

All Holesail connections use the Noise protocol for end-to-end encryption. See docs/SECURITY.md for the full security model.

Compatibility

Chrome 88+, Edge 88+, Firefox 79+
macOS, Linux, Windows
Desktop only (native messaging is not available on mobile browsers)

License

MIT

README.md Unescape Escape

Holesail Browser