Skip to content

docs: add macOS installer warning guidance #274

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mason5052 wants to merge 3 commits into
base: main
Choose a base branch
from
Open

docs: add macOS installer warning guidance #274

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
acd1b06
docs: add macOS installer warning guidance
mason5052 Apr 22, 2026
ffdeec2
docs: refine macOS installer warning guidance
mason5052 Apr 28, 2026
1cd643f
docs: tighten macOS installer warning guidance
mason5052 May 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
20 changes: 19 additions & 1 deletion backend/docs/installer/installer-troubleshooting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Comment thread
mason5052 marked this conversation as resolved.
Outdated
- The warning may be related to embedded Jaeger ClickHouse plugin binaries, but that is still unconfirmed.
Comment thread
mason5052 marked this conversation as resolved.
Outdated

**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.
Comment thread
mason5052 marked this conversation as resolved.
Outdated
- 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**
Expand Down Expand Up @@ -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
- **Recovery**: Graceful error handling and state restoration
Loading