Getting Started

Follow this guide to download, install, configure, and launch Quiper on your Mac.

---

System Requirements

Quiper is compatible with:

• Operating System: macOS 14.0 (Sonoma) or newer.
• Hardware: Intel-based Macs and Apple Silicon (M1, M2, M3, M4 series) Macs.
• Dependencies: None (all engine runtimes are hosted locally via WKWebViews or connected to cloud API services).

---

Installation

1. Download the Application

• Download the latest pre-compiled disk image (Quiper.dmg) from the Releases page.

2. Copy to Applications

• Double-click the Quiper.dmg file to mount it.
• Drag the Quiper icon into your /Applications directory.

---

Bypassing macOS Gatekeeper

Because Quiper is open-source and compiled transparently in the cloud via GitHub Actions, it is not signed with a paid Apple Developer ID. When you launch it for the first time, macOS Gatekeeper will block execution and show an alert: "Quiper cannot be opened because the developer cannot be verified."

To bypass this check safely:

1. Close the Gatekeeper alert dialogue.
2. Navigate to System Settings ➔ Privacy & Security.
3. Scroll down to the Security section.
4. You will see a note saying: "Quiper was blocked from use because it is not from an identified developer."
5. Click the Open Anyway button.
6. Enter your macOS user password or verify via Touch ID.
7. Relaunch Quiper. In the final confirmation dialog, click Open. macOS will remember this exception for the app bundle.

---

Initial Setup & Launching

When you launch Quiper, it will run as a status bar application:

• MenuBar Icon: You will see the Quiper logo in your macOS Menu Bar.
• Default Summon Hotkey: Press ⌥ Space (Option + Space) to summon the floating overlay.
• Hiding: Press ⌥ Space again (or press Escape / ⌘ H) to dismiss the window.

Notification Permissions

• When Quiper is first opened, macOS will prompt you to allow notifications.
• Crucial: Grant notification access if you plan to use background generation. Quiper’s built-in Web Notification bridge routes web page notifications directly to native macOS user notifications when your chat runs in the background.

Launch at Login

• To ensure Quiper is always active when you reboot your Mac:
  1. Open the Quiper overlay (⌥ Space).
  2. Press ⌘ , (Command + Comma) to open Settings.
  3. Go to the General tab.
  4. Toggle Start at Login to ON. This will write a standard LaunchAgent plist file under ~/Library/LaunchAgents/com.<username>.quiper.plist.

---

Release & Update Channels

You can customize your preferred update channel and manage automated checks or background downloads under the Updates tab. For a detailed reference of updates preferences and channels (Stable, Beta, Nightly), see the Application Settings Guide.

---

Verifying Build Security (Optional)

Since running unsigned apps requires trust, you can verify that the binary you downloaded matches the source code in this repository:

1. Ensure you have the GitHub CLI installed (brew install gh).
2. Open Terminal.
3. Run the cryptographic build provenance verification command:

   gh attestation verify /Applications/Quiper.app --repo sassanh/quiper

4. A successful output guarantees the binary was generated by GitHub Actions directly from the public codebase and has not been altered since compilation.