Installation Guide

Two ways to get Rift up and running on your Mac.

Before you start

✓ Apple Silicon — M1, M2, M3, or M4 chip required
✓ macOS Sonoma 14.0+ — or later
✓ 8GB RAM — minimum, 16GB recommended
✓ ~2GB disk space — for ML models (downloaded on first launch)

Recommended

Option A: Download

The fastest way to get started. One file, drag and drop.

1

Download the DMG

Click the button below to download the latest version (~400MB).

Download Rift for macOS

Free · Open Source · View on GitHub

2

Install the app

Open the downloaded DMG file and drag Rift to your Applications folder.

Rift

→

Applications

3

Launch Rift

Open Rift from your Applications folder or Spotlight (⌘ + Space, type "Rift").

On first launch, Rift will download ML models (~2GB). This takes 1-3 minutes depending on your internet speed.

4

Grant permissions

macOS will ask for two permissions:

🎤

Microphone

Required for voice dictation. Click "OK" when prompted.

⌨️

Accessibility

Required for keyboard shortcuts and text insertion. Go to System Settings → Privacy & Security → Accessibility and enable Rift.

✓

You're ready!

Press Ctrl + 1 to read selected text, or Ctrl + 2 to start dictation.

⚠️

macOS Security Warning

If macOS says the app is "damaged" or from an "unidentified developer", don't worry — this is expected.

Why this happens

Rift is not yet code-signed with an Apple Developer certificate. macOS Gatekeeper blocks unsigned apps by default to protect you. We're working on getting code signing set up — until then, here's the fix:

The fix (30 seconds)

Open Terminal (press ⌘ + Space, type "Terminal")
Copy and paste this command:

xattr -cr /Applications/Rift.app

Press Enter
Try launching Rift again — it should work now!

This command removes the quarantine flag that macOS adds to downloaded files. It's safe and only affects the Rift app.

For Developers

Option B: Build from Source

Clone the repository and build locally. Requires Node.js and Bun.

1

Clone the repository

git clone https://github.com/mkmk10k/rift.git && cd rift

2

Install dependencies

bun install

3

Bundle Python + MLX

bun run bundle:python

This downloads Python 3.11 and pre-installs all ML packages (~1GB)

4

Run in development mode

bun run dev

Troubleshooting

Common issues and how to fix them.

"The app is damaged"

Run the xattr command above. macOS blocks unsigned apps by default.

"Nothing happens when I speak"

Check that Microphone permission is granted in System Settings → Privacy & Security → Microphone.

"Keyboard shortcuts don't work"

Enable Accessibility permission in System Settings → Privacy & Security → Accessibility.

"Models won't download"

Check your internet connection. The first launch requires ~2GB download from Hugging Face.

"It's very slow"

First launch downloads models and may take a few minutes. Subsequent launches are instant.

"App crashes on launch"

Ensure you have an Apple Silicon Mac (M1/M2/M3/M4). Intel Macs are not supported.

Need help?

If you're stuck, here's how to get support:

📋

Copy Diagnostics

Click the Rift icon in your menu bar → Copy Diagnostics. This copies system info you can share when reporting issues.

𝕏

Reach out on X

DM or mention @kibu3000 with your issue. Include your diagnostics for faster help.

🐛

Open a GitHub Issue

For bugs or feature requests. Paste your diagnostics in the issue for context.

What diagnostics look like

=== RIFT DIAGNOSTICS ===
App Version: 2026.1.4
macOS: 25.2.0 (arm64)
CPU: Apple M3 Pro
RAM: 18GB

--- PYTHON BUNDLE ---
Exists: true
mlx: OK
parakeet_mlx: OK
kokoro: OK
=== END DIAGNOSTICS ===