T

CI / Build & Test (push) Successful in 3m47s

Details

- Build: explicitly write tt-native package.json into the bundle in

patchBundle so the runtime never gets empty content for that key
  (fixes "Unexpected end of JSON input" in Module._extensions..json
  when the host is started by the extension on Windows).
- State: treat empty or whitespace-only state.json (and legacy
  persist file) as missing and return default state instead of
  throwing in JSON.parse.
- State: add ensureStorageDir() and call it from message-router
  after setStoragePath so the storage directory exists on fresh
  install before any state is loaded or saved.

2026-03-06 18:51:53 -05:00

.gitea/workflows

chore(native-host): group modules into proxy/, managers/, host/

2026-03-03 23:53:51 -05:00

docs

Document Linux CA install: system store + manual browser import

2026-03-06 18:11:45 -05:00

extension

Update CSS - GN

2026-03-03 04:26:27 -05:00

native-host

- Build: explicitly write tt-native package.json into the bundle in

2026-03-06 18:51:53 -05:00

scripts

- Build: explicitly write tt-native package.json into the bundle in

2026-03-06 18:51:53 -05:00

.gitignore

Remove test dir, remove releases dir, adds dev releases to ignore.

2026-03-04 01:53:23 -05:00

CHANGELOG.md

fix(native-host): use host-specific tt-native resolution so Linux binary loads addon

2026-03-04 01:37:35 -05:00

com.holesail.browser.json

first commit

2026-02-27 18:13:59 -05:00

LICENSE

Convert license to AGPLV3

2026-03-02 16:35:53 -05:00

package-lock.json

first commit

2026-02-27 18:13:59 -05:00

package.json

Convert license to AGPLV3

2026-03-02 16:35:53 -05:00

README.md

Convert license to AGPLV3

2026-03-02 16:35:53 -05:00

README.md

Holesail Browser

Browse P2P Holesail tunnels directly in your browser. Holesail Browser is a Chrome/Firefox extension paired with a native host that routes virtual host domains (e.g. *.hole.sail or any private TLD you choose) 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 (and any other custom TLDs) → local CONNECT proxy (port 8442)
The CONNECT proxy pipes the raw TLS stream to the HTTPS proxy (port 8443)
The HTTPS proxy reads the TLS ClientHello, extracts the SNI hostname, and presents a per-TLD wildcard cert (signed by the local CA)
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/ or any custom private TLD (e.g. https://api.my.internal/)
Custom TLDs — use any private two-tier TLD, not just .hole.sail; PAC script and certificates are updated automatically
Server Tunnels — expose a local port as an hs:// key (TCP or UDP); supports an optional label for easy identification
Service Tunnels — forward a remote hs:// peer to a local TCP port
SSH — in-browser SSH terminal via xterm.js, over a Holesail tunnel; supports public key, saved password, and interactive auth
Remote Desktop — VNC (noVNC) and RDP viewer in the browser, over a Holesail tunnel; passwords saved securely
Backups — tar.gz snapshots of all state and certificates, with configurable retention
Auto CA — generates and installs a local root CA; issues per-TLD wildcard certs on demand via JS-layer SNI
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 Overview 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 (e.g. myapp.hole.sail) and its hs:// key
Navigate to https://myapp.hole.sail/

Note: The CA must be installed and Chrome must be restarted before virtual host sites will load without a certificate warning. You can use any private two-tier TLD — not just .hole.sail.

Dashboard pages

The dashboard uses a single topbar title per page. The Overview page is the landing page and features a sticky Quick Actions bar at the bottom with equal-height scrollable list cards for all data types.

Page	Description
Overview	Status summary, stat cards, scrollable lists for all data types, Quick Actions
Virtual Hosts	Map `hs://` keys to hostnames on any private TLD
Server Tunnels	Expose local ports as `hs://` keys (TCP/UDP), with optional label
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

Virtual host 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
Virtual Hosts — custom TLDs, certificate generation, deep hostnames
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

GNU Affero General Public License v3.0 (AGPL-3.0). See LICENSE for the full text.