From acd1b06b049ff65b404d0d1c0e2a086b5a6e5dbd Mon Sep 17 00:00:00 2001 From: mason5052 Date: Wed, 22 Apr 2026 13:02:00 -0400 Subject: [PATCH 1/3] 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 7ddc15baa..5edce2e33 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 aa0368ac6..a37fad20f 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 From 47ca10d945ccabb6eacf7be13190b96bdcf62362 Mon Sep 17 00:00:00 2001 From: "Mason Kim(ZINUS US_SALES)" Date: Tue, 28 Apr 2026 19:03:09 -0400 Subject: [PATCH 2/3] docs: refine macOS installer warning guidance --- backend/docs/installer/installer-troubleshooting.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/backend/docs/installer/installer-troubleshooting.md b/backend/docs/installer/installer-troubleshooting.md index a37fad20f..81d28d420 100644 --- a/backend/docs/installer/installer-troubleshooting.md +++ b/backend/docs/installer/installer-troubleshooting.md @@ -144,13 +144,13 @@ func (m *FormModel) ensureFocusVisible() { - 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. +- The maintainers reported in that issue that they contacted Apple about the warning and are waiting for a response. **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. +- If you trust the official release after verification, try to open the installer once, then open **System Settings** -> **Privacy & Security**, scroll to the security section that says the installer was blocked, click **Open Anyway**, and confirm the follow-up prompt to allow that specific app to run. +- If your version of macOS shows different wording, follow Apple's guidance for opening a Mac app from an unidentified developer: . - Do not reuse an installer archive that was downloaded from an unknown source, even if its filename matches the official archive name. ### **Navigation Issues** From 8f90b2abd359b54f354e248a92ec933812e85c7c Mon Sep 17 00:00:00 2001 From: mason5052 Date: Tue, 5 May 2026 16:14:58 -0400 Subject: [PATCH 3/3] docs: tighten macOS installer warning guidance --- README.md | 2 +- backend/docs/installer/installer-troubleshooting.md | 7 +++---- 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 5edce2e33..ca7dd7c45 100644 --- a/README.md +++ b/README.md @@ -578,7 +578,7 @@ 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. +> **macOS security warning:** If macOS flags a downloaded installer, use only the official PentAGI links above, choose the archive that matches your CPU architecture, verify the source before continuing, and follow 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):** diff --git a/backend/docs/installer/installer-troubleshooting.md b/backend/docs/installer/installer-troubleshooting.md index 81d28d420..18eb46067 100644 --- a/backend/docs/installer/installer-troubleshooting.md +++ b/backend/docs/installer/installer-troubleshooting.md @@ -142,14 +142,13 @@ func (m *FormModel) ensureFocusVisible() { **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. -- The maintainers reported in that issue that they contacted Apple about the warning and are waiting for a response. +- Maintainer notes in [issue #249](https://github.com/vxcontrol/pentagi/issues/249) report that the installer files are signed with the project certificate and that the checked `arm64` and `amd64` builds had zero VirusTotal detections. +- The maintainers have contacted Apple about the warning and are awaiting a response. **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, try to open the installer once, then open **System Settings** -> **Privacy & Security**, scroll to the security section that says the installer was blocked, click **Open Anyway**, and confirm the follow-up prompt to allow that specific app to run. +- If you trust the official release after verification, try to open the installer once. Then open **System Settings** -> **Privacy & Security**, find the security message that says the installer was blocked, click **Open Anyway**, and confirm the follow-up prompt to allow that specific app to run. - If your version of macOS shows different wording, follow Apple's guidance for opening a Mac app from an unidentified developer: . - Do not reuse an installer archive that was downloaded from an unknown source, even if its filename matches the official archive name.