Updates

Update Overview

Guardian checks for updates on startup, on focus, and every 15 minutes while the app is open. When an update is available you can install it from the update banner or Settings > Updates.

Update Source

Guardian reads updater metadata from the public distribution repository (GitHub Releases).

Release Structure

Distribution Repository
├── latest.json              # Current version metadata
├── Guardian_X.Y.Z_aarch64.app.tar.gz   # macOS updater artifact
├── Guardian_X.Y.Z_aarch64.dmg          # macOS installer
└── ...

latest.json Format

{
  "version": "vX.Y.Z",
  "notes": "Bug fixes and performance improvements",
  "pub_date": "2026-02-07T12:00:00Z",
  "platforms": {
    "darwin-aarch64": {
      "signature": "base64-signature",
      "url": "https://github.com/<org>/<repo>/releases/download/vX.Y.Z/Guardian_X.Y.Z_aarch64.app.tar.gz"
    }
  }
}

In-App Update Flow

Automatic Update Check

Guardian checks for updates:

1. On Startup: When you open the app
2. Manually: Via Settings > Updates > Check Now

Update Notification

When an update is available:

1. Banner appears at the top of the window
2. Version info shows in Settings > Updates

Update Installation Process

1. Notification Shown
       ↓
2. User Approves
       ↓
3. Download in Background
       ↓
4. Verify Update (integrity / signature / version)
       ↓
5. Install Update
       ↓
6. Restart Application
       ↓
7. New Version Active

Installation Steps:

1. Approval: Click "Install Update" in the banner or Settings
2. Download: Package downloads in background (progress shown)
3. Verification: The updater validates the update (for example: signature checks depending on your configuration)
4. Installation: The updater installs the new version
5. Restart: App restarts automatically
6. Confirmation: New version number shown in Settings

Update Verification

Before applying updates, Guardian verifies:

Check	Purpose
Updater Verification	Authenticity and integrity checks (depends on updater configuration)
Version Format	Prevents invalid updates

If any check fails, the update is rejected and the user is notified.

Update Settings

The current app experience focuses on startup checks, focus checks, and manual checks in Settings > Updates.

Manual Updates

Checking Manually

Settings > Updates > Check Now

Forces immediate check regardless of schedule.

Downloading Manually

If automatic updates fail:

1. Visit the download page on this website (/download)
2. Download installer for your platform
3. Run installer (previous version will be replaced)

Offline Updates

For air-gapped systems:

1. Download installer on connected machine
2. Transfer via USB/sneakernet
3. Run installer normally

Rollback

Manual Rollback

macOS:

# Restore from Time Machine
# Or reinstall previous version from backup

Operational Notes

Release Mirroring

If release mirroring is manual, verify that:

• latest.json points to distribution repository URLs
• Checksums match the actual files
• Signatures are valid
• Files are publicly accessible

Corporate Deployments

For enterprise environments:

1. Disable Auto-Update: Use internal policy and avoid in-app updates
2. Internal Mirror: Host latest.json on internal server
3. Staging: Test updates in staging environment first
4. Scheduled Deployment: Plan updates during maintenance windows
5. Group Policy: Configure via MDM or configuration management

Internal Mirror Setup:

{
  "version": "X.Y.Z",
  "downloads": {
    "darwin": {
      "url": "https://internal.company.com/guardian/Guardian-X.Y.Z.dmg"
    }
  }
}

Point Guardian to your internal update feed by setting the GUARDIAN_UPDATE_FEED_URL environment variable for the app runtime.

Update Notifications

Disable notifications temporarily:

• Do Not Disturb: System setting
• Focus Mode: macOS Focus

Troubleshooting Updates

Update check fails

Causes:

• Network connectivity issues
• Firewall blocking your update host
• Proxy not configured

Solutions:

1. Check internet connection
2. Verify update host accessibility
3. Configure proxy if behind corporate firewall
4. Try manual download

Download stuck or slow

Solutions:

1. Check bandwidth usage
2. Pause and resume download
3. Try different network
4. Use manual download as alternative

"Update verification failed"

Cause: Corrupted download or signature mismatch

Solutions:

1. Retry the update
2. Download a manual installer from the download page

Update installed but version unchanged

Solutions:

1. Fully quit Guardian (not just close window)
2. Restart application
3. Check if multiple versions installed
4. Reinstall manually if needed

Security Considerations

• Prefer updates from trusted distribution sources (official releases or your organization's internal mirror).
• Signature and integrity checks are performed by the updater depending on how your build and update source are configured.
• For custom update feeds, treat downloads as untrusted unless you have an independent verification process in place.

Getting Update Help

If update issues persist:

1. Check your network connectivity and try again.
2. Try a manual installer from the download page.
3. If you are using a custom update source, verify the URL and the feed response format.
4. Report the issue in the repository you are using and include the app version plus the error message you see.