Browse P2P Holesail tunnels directly in your browser. Holesail Browser is a Chrome/Firefox extension paired with a native host that routes *.hole.sail domains through Holesail tunnels — with automatic TLS, no port-forwarding, and no central servers.

How it works

You add a virtual host in the dashboard: myapp.hole.sail → hs://abc123...
The extension sets a PAC script that routes *.hole.sail → local CONNECT proxy (port 8442)
The CONNECT proxy pipes the raw TLS stream to the HTTPS proxy (port 8443)
The HTTPS proxy terminates TLS (using a locally-trusted wildcard cert) and forwards HTTP to the Holesail tunnel
The Holesail tunnel connects P2P to the remote peer over the DHT

All traffic is end-to-end encrypted via the Noise protocol. The local CA is only used for the browser↔proxy TLS leg.

Features

Virtual Hosts — browse any hs:// URL as https://name.hole.sail/
Server Tunnels — expose a local port as an hs:// key (TCP or UDP)
Service Tunnels — forward a remote hs:// peer to a local TCP port
SSH — in-browser SSH terminal via xterm.js, over a Holesail tunnel
Remote Desktop — VNC (noVNC) and RDP viewer in the browser, over a Holesail tunnel
Backups — tar.gz snapshots of all state and certificates, with configurable retention
Auto CA — generates and installs a local root CA; signs a wildcard *.hole.sail cert
Persistent state — all tunnels, connections, and settings survive restarts

Installation

macOS / Linux (recommended)

curl -fsSL https://git.ssh.surf/snxraven/holesail-browser/raw/branch/main/scripts/web-installer.sh | bash

Windows

Download and run the PowerShell installer:

irm https://git.ssh.surf/snxraven/holesail-browser/raw/branch/main/scripts/install.ps1 | iex

Or download install.ps1 from the latest release and run it manually.

What the installer does

Downloads the pre-built native host binary for your platform from the latest release
Installs it to ~/.holesail-browser/ (macOS/Linux) or %LOCALAPPDATA%\holesail-browser\ (Windows)
Writes the native messaging manifest so Chrome/Firefox can find it
Downloads the extension .zip (Chrome) and .xpi (Firefox) to ~/Downloads
On macOS: removes Gatekeeper quarantine and ad-hoc signs the binary and native addons

Loading the extension

Chrome / Edge

Open chrome://extensions
Enable Developer mode (top right)
Drag ~/Downloads/Holesail-Browser-1.0.0.zip onto the page
(or click Load unpacked after extracting the zip)

Firefox (regular)

Firefox requires extensions to be signed by Mozilla for permanent installation. Use the temporary add-on loader instead:

Open about:debugging
Click This Firefox
Click Load Temporary Add-on...
Select ~/Downloads/Holesail-Browser-1.0.0.zip (or any file inside the extracted folder)

Note: Temporary add-ons are removed when Firefox restarts. You will need to reload it each time.

Firefox Developer Edition / Nightly (permanent, unsigned)

Developer Edition and Nightly allow disabling signature enforcement:

Open about:config → search for xpinstall.signatures.required → set it to false
Open about:addons → gear icon → Install Add-on From File
Select ~/Downloads/Holesail-Browser-1.0.0.xpi

Firefox (permanent, signed)

For a permanent install in regular Firefox, the extension must be signed by Mozilla via addons.mozilla.org. Self-hosted distribution (no public listing required) is available — see docs/INSTALLATION.md for details.

First run

Click the Holesail Browser icon in your toolbar to open the dashboard
Go to Proxy & CA → click Install Root CA
Fully quit and reopen Chrome (Cmd+Q on macOS) for the CA trust to take effect
Go to Virtual Hosts → add a hostname and hs:// key
Navigate to https://your-hostname.hole.sail/

Note: The CA must be installed and Chrome must be restarted before *.hole.sail sites will load without a certificate warning.

Dashboard pages

Page	Description
Overview	Status summary, connection count, proxy ports
Virtual Hosts	Map `hs://` keys to `*.hole.sail` hostnames
Server Tunnels	Expose local ports as `hs://` keys (TCP/UDP)
Service Tunnels	Forward remote `hs://` peers to local TCP ports
Proxy & CA	Proxy port settings, CA install/status
SSH	In-browser SSH terminal over Holesail
Remote Desktop	VNC/RDP viewer over Holesail
Backups	Create, restore, and manage backups
Logs	Live log stream from the native host
Settings	Proxy ports, timeouts, notifications, debug mode

File locations

Path	Description
`~/.holesail-browser/holesail-browser-host`	Native host binary
`~/.holesail-browser/holesail-browser-storage/state.json`	All persistent state
`~/.holesail-browser/holesail-browser-certs/`	CA and domain certificates
`~/.holesail-browser/holesail-browser.log`	Native host log file
`~/.holesail-browser/holesail-browser-storage/backups/`	Backup archives

Troubleshooting

*.hole.sail sites show a certificate error

The root CA is not trusted, or Chrome was not restarted after installing it. Open the dashboard → Proxy & CA and check the CA status. If it shows "Not Installed", click Install Root CA, then fully quit and reopen Chrome (Cmd+Q).

If the CA shows "Installed" but you still see errors, the keychain may have a stale entry from a previous installation. Click Install Root CA again — it will detect the mismatch, remove the old entry, and install the correct one.

No tunnel for this hostname

The native host has no active tunnel for that hostname. Possible causes:

The tunnel is still connecting — wait a few seconds and refresh
The native host was restarted and is reconnecting — open the dashboard to check
The hostname in the dashboard doesn't exactly match what you're browsing

Native host not connecting / hostConnected: false

Make sure you haven't started holesail-browser-host manually from a terminal — only Chrome should spawn it via native messaging
Check ~/.holesail-browser/holesail-browser.log for errors
Try reloading the extension at chrome://extensions

macOS: "Apple cannot verify..." / Gatekeeper warning

Run the installer again — it handles quarantine removal and ad-hoc signing automatically. If you moved the binary manually, run:

xattr -rd com.apple.quarantine ~/.holesail-browser/holesail-browser-host
codesign --force --sign - ~/.holesail-browser/holesail-browser-host

Access to the specified native messaging host is forbidden

The extension ID in the native messaging manifest doesn't match the installed extension. Re-run the installer, or manually update the allowed_origins field in the manifest JSON to match the extension ID shown in chrome://extensions.

Building from source

git clone https://git.ssh.surf/snxraven/holesail-browser
cd holesail-browser
npm install
cd native-host && npm install && cd ..

# Build extension
npm run pack

# Build native host binary for current platform
npm run build:dist

# Build for all platforms
npm run build:dist:all

The built extension will be in releases/Holesail-Browser-*.zip and .xpi. Platform binaries will be in releases/<platform>-<arch>/.

Platform support

Platform	Architecture	Binary
macOS	Apple Silicon (arm64)	`darwin-arm64`
macOS	Intel (x64)	`darwin-x64`
Linux	x64	`linux-x64`
Linux	ARM64	`linux-arm64`
Windows	x64	`win32-x64` (.exe)

Documentation

Architecture — system design, component overview, message flow
Installation — detailed install guide for all platforms
Tunneling — virtual hosts, server tunnels, service tunnels
SSH — in-browser SSH terminal
Remote Desktop — VNC and RDP over Holesail
Backups — backup and restore
Security — CA model, encryption, threat model
Native Host Protocol — message types and API reference

License

MIT