# Installation

## Quick install

### macOS / Linux

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

### Windows (PowerShell)

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

Or download `install.ps1` from the [latest release](https://git.ssh.surf/snxraven/holesail-browser/releases/tag/latest-main) 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](https://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](https://addons.mozilla.org/developers/)
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](https://addons.mozilla.org/developers/) 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:

```bash
# 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

```bash
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

```powershell
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](https://nodejs.org/) 18+
- [Bare](https://github.com/holepunchto/bare) runtime (for running the native host in development)
- npm

### Steps

```bash
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

```bash
# 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 |