> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# macOS Desktop App

> Install the PraisonAI Mac desktop app and get past Gatekeeper on first launch

Install the PraisonAI Mac desktop app, understand the two Gatekeeper messages you may see, and open the app on first launch.

<Warning>
  **Do not download v4.7.2.** That build shipped with an invalid signature and cannot be opened on any Mac. v4.7.3 and later are ad-hoc signed and open with right-click → Open.
</Warning>

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Start[First launch of PraisonAI.app] --> Q{Which message?}
    Q -->|"unidentified developer" / "cannot check for malicious software"| A[Right-click → Open → Open]
    Q -->|"PraisonAI is damaged and can't be opened"| B[You are on v4.7.2 — upgrade to v4.7.3 or later]
    A --> Done[App launches; provisions Python on first run]
    B --> Download[Download the latest .dmg from Releases]
    Download --> Done

    classDef q fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef fix fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef warn fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef done fill:#10B981,stroke:#7C90A0,color:#fff
    class Start,Q q
    class A,Download fix
    class B warn
    class Done done
```

## Download

Pick the build that matches your Mac. Open  → About This Mac: "Chip" means Apple silicon, "Processor" means Intel.

| Mac                   | Download                                      |
| --------------------- | --------------------------------------------- |
| Apple silicon (M1–M4) | `PraisonAI-<version>-macos-apple-silicon.dmg` |
| Intel                 | `PraisonAI-<version>-macos-intel.dmg`         |

There is no universal build. A wrong-arch download fails when you launch it, not when you install it.

## Quick Start

<Steps>
  <Step title="First launch (ad-hoc signed, v4.7.3+)">
    <Note>
      Gatekeeper refuses an app it cannot verify. The app carries an ad-hoc signature, which makes the signature *valid* but not *trusted* — so macOS says it cannot check for malicious software, or that the developer is unidentified.
    </Note>

    1. Drag **PraisonAI** to Applications.
    2. **Right-click** it → **Open** → **Open**.
    3. macOS remembers your choice; after that, double-click works.
  </Step>

  <Step title="Fallback if Gatekeeper still refuses">
    Clear the quarantine attribute your browser added when it downloaded the file, then reopen the app:

    ```sh theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    xattr -dr com.apple.quarantine /Applications/PraisonAI.app
    ```
  </Step>
</Steps>

***

## If you see *"PraisonAI is damaged and can't be opened"*

<Warning>
  That message means something different, and right-click → Open will **not** get past it: macOS says "damaged" when a signature is present but *invalid*, not when one is merely untrusted.

  **v4.7.2 shipped in exactly that state.** The bundle was never signed, so the only signature on it was the one the Rust linker leaves on the executable, and that signature declares a resource seal an unsigned bundle does not have. Every Mac rejected it. Use v4.7.3 or later; the release build now refuses to attach a macOS bundle whose signature does not verify.
</Warning>

***

## Two Gatekeeper messages

The message you see tells you which fix applies.

| Message                                                          | What it means                                 | Fix                        |
| ---------------------------------------------------------------- | --------------------------------------------- | -------------------------- |
| "unidentified developer" / "cannot check for malicious software" | Signature is valid but **untrusted**          | Right-click → Open → Open  |
| "PraisonAI is damaged and can't be opened"                       | Signature is present but **invalid** (v4.7.2) | Upgrade to v4.7.3 or later |

***

## First run

The app needs a Python environment to run its engine and offers to build one: it fetches `uv`, installs a pinned CPython, creates a virtual environment, and installs `praisonaiagents` into it. Roughly 500 MB, once.

Nothing is installed system-wide. The environment and your conversations live together in `~/Library/Application Support/PraisonAI`. To remove the app completely, uninstall it and delete that folder.

***

## Questions a fresh user asks

<AccordionGroup>
  <Accordion title="Why does macOS block the app at all?">
    The build is ad-hoc signed, not signed with a Developer ID. Gatekeeper trusts only Developer ID signatures, so it shows the "unidentified developer" warning. Right-click → Open bypasses it once.
  </Accordion>

  <Accordion title="How do I open it the first time?">
    Right-click the app → **Open** → **Open**. macOS remembers your choice; after that, double-click works.
  </Accordion>

  <Accordion title="macOS says &#x22;damaged&#x22; — is that the normal first-launch warning?">
    **No.** "Damaged" means the signature is invalid (v4.7.2 only). "Unidentified developer" is the normal first-launch warning. Only the second is bypassable with right-click → Open. If you see "damaged", upgrade to v4.7.3 or later.
  </Accordion>

  <Accordion title="Right-click → Open still refuses. What now?">
    Your browser attached a quarantine attribute. Clear it, then reopen:

    ```sh theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    xattr -dr com.apple.quarantine /Applications/PraisonAI.app
    ```
  </Accordion>
</AccordionGroup>

***

## Signing status

<Note>
  The Mac build is ad-hoc signed, which makes the signature valid but not trusted — Gatekeeper still shows the "unidentified developer" warning that right-click → Open bypasses. The release workflow verifies the signature before publishing, so a build that fails verification is never shipped. Full Developer ID signing (which removes the warning entirely) requires an Apple certificate in repository secrets; when that lands, the right-click step goes away.
</Note>

***

## Related

<CardGroup cols={2}>
  <Card title="Quick Install" icon="bolt" href="/docs/install/quickstart">
    Install the PraisonAI CLI with one command
  </Card>

  <Card title="Build Your First Agent" icon="robot" href="/docs/quickstart">
    Create an AI agent in 3 lines of code
  </Card>
</CardGroup>