From acd1b06b049ff65b404d0d1c0e2a086b5a6e5dbd Mon Sep 17 00:00:00 2001 From: mason5052 Date: Wed, 22 Apr 2026 13:02:00 -0400 Subject: [PATCH] docs: add macOS installer warning guidance --- README.md | 2 ++ .../installer/installer-troubleshooting.md | 20 ++++++++++++++++++- 2 files changed, 21 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 7ddc15ba..5edce2e3 100644 --- a/README.md +++ b/README.md @@ -578,6 +578,8 @@ PentAGI provides an interactive installer with a terminal-based UI for streamlin - **Windows**: amd64 [download](https://pentagi.com/downloads/windows/amd64/installer-latest.zip) - **macOS**: amd64 (Intel) [download](https://pentagi.com/downloads/darwin/amd64/installer-latest.zip) | arm64 (M-series) [download](https://pentagi.com/downloads/darwin/arm64/installer-latest.zip) +> **macOS security warning:** macOS may occasionally flag downloaded installer builds even when they are signed. Download the installer only from the official PentAGI links above, choose the archive that matches your CPU architecture, and see the [installer troubleshooting guide](backend/docs/installer/installer-troubleshooting.md#macos-reports-the-installer-as-malware) before allowing the app to run. + **Quick Installation (Linux amd64):** ```bash diff --git a/backend/docs/installer/installer-troubleshooting.md b/backend/docs/installer/installer-troubleshooting.md index aa0368ac..a37fad20 100644 --- a/backend/docs/installer/installer-troubleshooting.md +++ b/backend/docs/installer/installer-troubleshooting.md @@ -135,6 +135,24 @@ func (m *FormModel) ensureFocusVisible() { ## 🔧 **Common Issues & Solutions** +### **macOS Reports the Installer as Malware** + +**Symptoms**: macOS blocks a downloaded PentAGI installer and reports that it may contain malware. + +**What is currently known**: +- Use only the official PentAGI installer downloads linked from the project README. +- Select the archive that matches your Mac CPU architecture: `darwin/amd64` for Intel Macs or `darwin/arm64` for Apple silicon. +- The maintainers reported in [issue #249](https://github.com/vxcontrol/pentagi/issues/249) that the installer files are signed with the project certificate. +- The maintainers also reported zero VirusTotal detections for the checked `arm64` and `amd64` installer builds in that issue. +- Apple was contacted about the warning on March 24, 2026, and the project is waiting for Apple's response. +- The warning may be related to embedded Jaeger ClickHouse plugin binaries, but that is still unconfirmed. + +**Recommended handling**: +- Treat any unexpected malware warning as a reason to stop and verify the download source before continuing. +- Re-download the installer from the official PentAGI link if the archive came from a mirror, chat attachment, or any unofficial source. +- If you trust the official release after verification, use the normal macOS security flow to allow the installer for that one run. +- Do not reuse an installer archive that was downloaded from an unknown source, even if its filename matches the official archive name. + ### **Navigation Issues** #### **Navigation Stack Corruption** @@ -593,4 +611,4 @@ This troubleshooting guide provides comprehensive solutions for: - **Form Problems**: Responsive design and scrolling - **Configuration**: Environment variable management - **Performance**: Optimization and resource management -- **Recovery**: Graceful error handling and state restoration \ No newline at end of file +- **Recovery**: Graceful error handling and state restoration