holesail-browser/docs/BACKUP.md

Backups

Holesail Browser can create tar.gz snapshots of all persistent state and certificates. Backups can be created manually from the dashboard or restored at any time.

What is backed up

Each backup archive contains:

Path in archive	Source
storage/state.json	All virtual hosts, server tunnels (with labels), service tunnels, SSH connections (with passwordB64), RDP connections (with passwordB64), and settings
certs/ca.key.pem	Root CA private key
certs/ca.cert.pem	Root CA certificate
certs/wildcard.hole.sail/	Wildcard cert for the default .hole.sail TLD
certs/wildcard.<parent>/	One directory per custom TLD parent (e.g. wildcard.my.internal/, wildcard.haha.wooo/)

The entire holesail-browser-certs/ directory is archived — all wildcard cert directories are included, not just the default one. Backups do not include the binary itself, the log file, or other backup archives.

The default backup retention is 5 backups (configurable in Settings via backupRetention).

Storage location

Backups are stored at:

~/.holesail-browser/holesail-browser-storage/backups/

Each backup is a tar.gz file named with a timestamp:

holesail-browser-backup-2026-02-28T12-00-00.tar.gz

Usage

Creating a backup

1. Open the dashboard → Backups
2. Click Create Backup
3. The backup is created immediately and appears in the list

Restoring a backup

1. Open the dashboard → Backups
2. Find the backup you want to restore
3. Click Restore
4. The native host extracts the archive, overwrites the current state and certs, and reloads state from disk

After restoring a backup that contains different certificates, you may need to reinstall the root CA (dashboard → Proxy & CA → Install Root CA) and restart Chrome.

Deleting a backup

1. Open the dashboard → Backups
2. Click Delete next to the backup you want to remove

Retention

Backups are automatically pruned after each new backup is created. The default retention is 5 backups. To change it:

1. Open the dashboard → Settings
2. Set Backup Retention to the desired number
3. Click Save

---

Native host commands

createBackup

Create a new backup.

Request payload: {}

Response payload:

{
  "ok": true,
  "filename": "holesail-browser-backup-2026-02-28T12-00-00.tar.gz",
  "path": "/Users/you/.holesail-browser/holesail-browser-storage/backups/holesail-browser-backup-2026-02-28T12-00-00.tar.gz"
}

listBackups

List all available backups.

Response payload:

{
  "ok": true,
  "backups": [
    {
      "filename": "holesail-browser-backup-2026-02-28T12-00-00.tar.gz",
      "size": 12345,
      "createdAt": "2026-02-28T12:00:00.000Z"
    }
  ]
}

restoreBackup

Restore a backup by filename.

Request payload:

{ "filename": "holesail-browser-backup-2026-02-28T12-00-00.tar.gz" }

Response payload:

{ "ok": true }

deleteBackup

Delete a backup by filename.

Request payload:

{ "filename": "holesail-browser-backup-2026-02-28T12-00-00.tar.gz" }

Response payload:

{ "ok": true }

---

Implementation details

Creating a backup

1. A staging directory is created in the backups folder
2. state.json is copied to staging/storage/state.json
3. All cert files are copied to staging/certs/
4. tar czf <output.tar.gz> -C staging . creates the archive
5. The staging directory is removed
6. Old backups exceeding the retention count are deleted (oldest first)

Restoring a backup

1. The archive is extracted to a staging directory
2. If storage/state.json exists in the archive, it overwrites the current state.json
3. If certs/ exists in the archive, cert files are copied to the certs directory
4. The staging directory is removed
5. The native host reloads state from disk

Legacy archive support

Backups created by older versions of Holesail Browser used a flat layout (files at the root of the archive rather than under storage/ and certs/ prefixes). These are still supported for restore.

---

Troubleshooting

Backup creation fails

• Check that ~/.holesail-browser/holesail-browser-storage/backups/ is writable
• Check ~/.holesail-browser/holesail-browser.log for error details
• Ensure tar is available on the system

Restore doesn't take effect

After restoring, the native host reloads state from disk. If tunnels don't reconnect, open the dashboard — the Overview page will show the current state. You may need to manually reconnect tunnels if the restored state references different hs:// keys.

CA mismatch after restore

If the restored backup contains different CA certificates than what is currently installed in the OS keychain, *.hole.sail sites will show certificate errors. Go to dashboard → Proxy & CA → click Install Root CA to reinstall the correct CA, then restart Chrome.