holesail-browser/docs/INSTALLATION.md

Installation

Quick install

macOS / Linux

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

Windows (PowerShell)

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 from PowerShell.

---

What the installer does

macOS / Linux (install.sh)

1. Detects your OS and architecture (darwin/linux, x64/arm64)
2. Preserves existing user data — if a previous installation is found, holesail-browser-storage/ (state, settings, backups) and holesail-browser-certs/ (CA key and certificates) are copied to a temporary location before anything is removed
3. Kills any running holesail-browser-host process
4. Removes the previous installation directory and old native messaging manifests
5. Downloads holesail-browser-host-<platform>-<arch>.zip from the latest release
6. Extracts the binary to ~/.holesail-browser/holesail-browser-host
7. Restores user data — the preserved storage and certs directories are copied back, so all tunnels, connections, settings, and certificates survive the upgrade
8. macOS only: removes Gatekeeper quarantine, ad-hoc signs the binary, pre-runs it to extract .bare native addons, then signs all extracted addons
9. Removes old extension files — any existing Holesail-Browser-*.zip and Holesail-Browser-*.xpi files in ~/Downloads are deleted before downloading the new version
10. Downloads Holesail-Browser-1.0.0.zip and Holesail-Browser-1.0.0.xpi to ~/Downloads
11. Writes the native messaging manifest to all browser locations

Windows (install.ps1)

1. Preserves existing user data — if a previous installation is found, holesail-browser-storage\ and holesail-browser-certs\ are copied to a temporary location in %TEMP%
2. Kills any running holesail-browser-host.exe process
3. Removes the previous installation directory and old registry keys
4. Downloads holesail-browser-host-win32-x64.zip and extracts the .exe
5. Restores user data — the preserved directories are copied back into the new installation
6. Removes old extension files — any existing Holesail-Browser-*.zip and Holesail-Browser-*.xpi files in %USERPROFILE%\Downloads are deleted before downloading the new version
7. Downloads Holesail-Browser-1.0.0.zip and Holesail-Browser-1.0.0.xpi to %USERPROFILE%\Downloads
8. Writes the native messaging manifest JSON and creates registry keys for Chrome, Chromium, and Firefox

What is preserved across upgrades

Directory	Contents
holesail-browser-storage/	state.json (all virtual hosts, tunnels, SSH/RDP connections, settings), backup archives
holesail-browser-certs/	Root CA key and certificate, all wildcard domain certs (one per custom TLD parent, e.g. wildcard.hole.sail/, wildcard.my.internal/)

The binary itself is always replaced with the new version. If this is a fresh install (no previous ~/.holesail-browser/ directory), the preserve/restore steps are skipped.

---

Native messaging manifest locations

The installer writes the manifest to all of these locations automatically:

macOS

Browser	Path
Chrome	~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.holesail.browser.json
Chromium	~/Library/Application Support/Chromium/NativeMessagingHosts/com.holesail.browser.json
Firefox	~/Library/Application Support/Mozilla/NativeMessagingHosts/com.holesail.browser.json

Linux

Browser	Path
Chrome	~/.config/google-chrome/NativeMessagingHosts/com.holesail.browser.json
Chromium	~/.config/chromium/NativeMessagingHosts/com.holesail.browser.json
Firefox	~/.mozilla/native-messaging-hosts/com.holesail.browser.json

Windows

Registry keys under HKCU\Software\:

• Google\Chrome\NativeMessagingHosts\com.holesail.browser
• Chromium\NativeMessagingHosts\com.holesail.browser
• Mozilla\NativeMessagingHosts\com.holesail.browser

Each key's default value points to the manifest JSON file at %LOCALAPPDATA%\holesail-browser\com.holesail.browser.json.

---

Loading the extension

Chrome / Edge

1. Open chrome://extensions
2. Enable Developer mode (toggle in the top right)
3. Drag ~/Downloads/Holesail-Browser-1.0.0.zip onto the extensions page
   (or click Load unpacked and select the extracted folder)

Firefox (regular)

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

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

Temporary add-ons are removed when Firefox restarts — you will need to reload it each session.

Firefox Developer Edition / Nightly (permanent, unsigned)

Developer Edition and Nightly allow disabling Mozilla's signature requirement:

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

Firefox (permanent, signed via AMO)

For a permanent install in regular Firefox without any workarounds, the extension must be submitted to addons.mozilla.org (AMO) and signed by Mozilla. Once signed, the .xpi can be installed permanently in any Firefox version via about:addons.

The signing process:

1. Create an account at addons.mozilla.org
2. Submit the .xpi for review (self-hosted distribution is available — full AMO listing is not required)
3. Mozilla signs and returns the .xpi
4. Distribute the signed .xpi — users can install it via about:addons without any config changes

Self-hosted signing (without a public AMO listing) is available via the AMO Developer Hub under Submit a New Add-on → On your own.

---

Installing the dashboard as a standalone app (PWA)

The dashboard supports being installed as a standalone desktop app via Chrome's PWA install feature. This opens the dashboard in its own OS window without any browser chrome (no address bar, tabs, or toolbar).

Requirements: The Holesail Browser extension must already be installed. The PWA is a launcher only — all functionality still runs through the extension and native host.

How to install

1. Open the dashboard (click the Holesail icon in the toolbar, or press Alt+Shift+H)
2. In Chrome, open the browser menu (⋮ top right) → Save and share → Install page as app
3. Confirm the install prompt — the dashboard will appear in your OS app launcher and dock

Once installed, you can open Holesail directly from your desktop without opening a browser tab first.

Uninstalling the PWA

In Chrome, go to chrome://apps, right-click Holesail Browser, and select Remove from Chrome. This removes the standalone app shortcut but does not affect the extension itself.

Note: The PWA requires the extension to remain installed. If you uninstall the extension, the installed app will no longer function.

---

First-time setup

After loading the extension:

1. Click the Holesail Browser icon in the toolbar to open the dashboard
2. Go to Proxy & CA → click Install Root CA
3. Fully quit and reopen Chrome (Cmd+Q on macOS, Alt+F4 on Windows) for the CA trust to take effect
4. Go to Virtual Hosts → add a hostname (e.g. myapp.hole.sail) and its hs:// key
5. Navigate to https://myapp.hole.sail/

The root CA must be installed and Chrome must be restarted before *.hole.sail sites will load without a certificate warning. The CA is installed silently to your user keychain — no admin password is required on macOS.

---

Updating the extension ID

The native messaging manifest contains an allowed_origins field with the extension's Chrome ID. If you load the extension from a different source (e.g. a locally built zip), the ID may differ.

To update it, run:

# macOS / Linux
bash scripts/update-native-manifest-extension-id.sh <new-extension-id>

# Windows
.\scripts\update-native-manifest-extension-id.ps1 <new-extension-id>

Or edit the manifest JSON files directly and replace the chrome-extension://... value in allowed_origins.

---

Uninstalling

macOS / Linux

pkill -f holesail-browser-host 2>/dev/null || true
rm -rf ~/.holesail-browser

# Remove native messaging manifests
rm -f ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.holesail.browser.json
rm -f ~/Library/Application\ Support/Chromium/NativeMessagingHosts/com.holesail.browser.json
rm -f ~/Library/Application\ Support/Mozilla/NativeMessagingHosts/com.holesail.browser.json

# Remove CA from keychain (macOS)
security delete-certificate -c "Holesail Browser CA" ~/Library/Keychains/login.keychain-db 2>/dev/null || true

Windows

Stop-Process -Name holesail-browser-host -Force -ErrorAction SilentlyContinue
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\holesail-browser"
Remove-Item -Path "HKCU:\Software\Google\Chrome\NativeMessagingHosts\com.holesail.browser" -ErrorAction SilentlyContinue
Remove-Item -Path "HKCU:\Software\Chromium\NativeMessagingHosts\com.holesail.browser" -ErrorAction SilentlyContinue
Remove-Item -Path "HKCU:\Software\Mozilla\NativeMessagingHosts\com.holesail.browser" -ErrorAction SilentlyContinue

Then remove the extension from chrome://extensions.

---

Building from source

Prerequisites

• Node.js 18+
• Bare runtime (for running the native host in development)
• npm

Steps

git clone https://git.ssh.surf/snxraven/holesail-browser
cd holesail-browser

# Install root dependencies
npm install

# Install native host dependencies
cd native-host && npm install && cd ..

# Build extension (.zip + .xpi)
npm run pack

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

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

Built artifacts:

• releases/Holesail-Browser-*.zip — Chrome extension
• releases/Holesail-Browser-*.xpi — Firefox extension
• releases/<platform>-<arch>/holesail-browser-host[.exe] — native host binary

Running in development

# Run the native host directly with Bare
cd native-host
bare index.mjs

Load the extension/ directory as an unpacked extension in Chrome.

---

Environment variables

Variable	Description
HOLESAIL_DEBUG=1	Enable verbose debug logging in the native host
HOLESAIL_BROWSER_STORAGE=<path>	Override the storage directory (default: next to binary)
HOLESAIL_BROWSER_CERTS=<path>	Override the certs directory (default: next to binary)
BRIDGE_SWARM_LOG=<path>	Override the log file path