Skip to content

feat: streamline macOS install with DMG builds + cross-platform setup #41

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
shizzleclover wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat: streamline macOS install with DMG builds + cross-platform setup #41

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
20 changes: 16 additions & 4 deletions .github/workflows/release.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ jobs:
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest, windows-latest]
os: [ubuntu-latest, windows-latest, macos-latest]
include:
- os: ubuntu-latest
script: linux
Expand All @@ -32,6 +32,11 @@ jobs:
script: win
artifact_glob: |
dist/*.exe
- os: macos-latest
script: mac
artifact_glob: |
dist/*.dmg
dist/*.zip

steps:
- name: Checkout
Expand Down Expand Up @@ -180,14 +185,19 @@ jobs:
| Platform | File | Notes |
|---|---|---|
| **Windows** | `OpenCluely-Setup-*.exe` | NSIS installer — installs app + adds to Start Menu |
| **macOS (Apple Silicon)** | `OpenCluely-*-arm64.dmg` | Drag to Applications, then run quarantine fix below |
| **macOS (Intel)** | `OpenCluely-*-x64.dmg` | Drag to Applications, then run quarantine fix below |
| **Linux** | `*.deb` | Debian/Ubuntu — auto-pulls system deps (Python, ffmpeg, GTK) |
| **Linux** | `*.AppImage` | Universal — no install, just `chmod +x` and run |

> **macOS:** no pre-built build is shipped. The app is unsigned/un-notarized, so macOS Gatekeeper blocks it as "damaged". Run OpenCluely from source instead:
> **macOS quarantine fix (one-time):** Since this app is unsigned, macOS Gatekeeper blocks it.
> After dragging OpenCluely to Applications, open Terminal and run:
> ```bash
> git clone https://github.com/TechyCSR/OpenCluely && cd OpenCluely && ./setup.sh
> xattr -rd com.apple.quarantine /Applications/OpenCluely.app
> ```
> Requires Node.js 18+. See the [README](https://github.com/TechyCSR/OpenCluely#quick-start) for details.
> The app will open normally from then on.

> **Run from source** (any platform): `git clone https://github.com/TechyCSR/OpenCluely && cd OpenCluely && npm run setup`

## First Run

Expand Down Expand Up @@ -236,6 +246,8 @@ jobs:
# The order below is the order files appear in the release page.
find artifacts -type f -name 'OpenCluely-Setup-*.exe' \
-exec cp -v {} release/ \;
find artifacts -type f -name '*.dmg' \
-exec cp -v {} release/ \;
find artifacts -type f -name 'opencluely_*_amd64.deb' \
-exec cp -v {} release/ \;
find artifacts -type f -name '*.AppImage' \
Expand Down
61 changes: 36 additions & 25 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,19 +48,29 @@ Pre-built installers are published with every release. These links always point

| Platform | File | Notes |
|---|---|---|
| Windows | [Setup .exe](https://github.com/TechyCSR/OpenCluely/releases/latest) | NSIS installer. Adds a Start Menu shortcut. |
| Linux (Debian or Ubuntu) | [.deb](https://github.com/TechyCSR/OpenCluely/releases/latest) | Pulls system deps automatically (Python, ffmpeg, GTK). |
| Linux (universal) | [.AppImage](https://github.com/TechyCSR/OpenCluely/releases/latest) | No install. Run `chmod +x` then launch. |
| **Windows** | [Setup .exe](https://github.com/TechyCSR/OpenCluely/releases/latest) | NSIS installer. Adds a Start Menu shortcut. |
| **macOS (Apple Silicon)** | [.dmg (arm64)](https://github.com/TechyCSR/OpenCluely/releases/latest) | For M1/M2/M3/M4 Macs. See quarantine fix below. |
| **macOS (Intel)** | [.dmg (x64)](https://github.com/TechyCSR/OpenCluely/releases/latest) | For older Intel-based Macs. See quarantine fix below. |
| **Linux (Debian/Ubuntu)** | [.deb](https://github.com/TechyCSR/OpenCluely/releases/latest) | Pulls system deps automatically (Python, ffmpeg, GTK). |
| **Linux (universal)** | [.AppImage](https://github.com/TechyCSR/OpenCluely/releases/latest) | No install. Run `chmod +x` then launch. |

> **macOS:** there is no pre-built download. The app is unsigned and un-notarized, so macOS Gatekeeper blocks it as "damaged and can't be opened." Run OpenCluely from source instead — see [Quick start](#quick-start). It is a one-line `./setup.sh` once Node.js is installed.
### macOS installation

Since OpenCluely is open source and unsigned, macOS Gatekeeper will block it on first run. After downloading and dragging the app to Applications, run this **one-time fix** in Terminal:

```bash
xattr -rd com.apple.quarantine /Applications/OpenCluely.app
```

After that, the app opens normally like any other application — no further steps needed.

Every build is produced automatically on GitHub Actions and ships with SHA-256 checksums. Each release also lists the full set of commits it includes.

The website at [opencluely.techycsr.dev](https://opencluely.techycsr.dev) detects your operating system and offers the right installer directly.

## Quick start
## Quick start (run from source)

If you would rather build from source, three steps are all it takes.
If you prefer to build from source — or want to contribute — three steps are all it takes. This works on **macOS, Windows, and Linux** with no extra tools beyond Node.js.

1. Clone the repository.

Expand All @@ -69,33 +79,26 @@ If you would rather build from source, three steps are all it takes.
cd OpenCluely
```

2. Run the setup script.
2. Run the setup.

```bash
./setup.sh
npm run setup
```

The script installs Node dependencies, creates your `.env` from the example, sets up a local Whisper virtual environment, points the config at it, and launches the app.
This installs Node dependencies, creates your `.env` from the example, sets up a local Whisper virtual environment, points the config at it, and launches the app. On macOS and Linux, `./setup.sh` also works.

3. Add your Gemini key.

On first launch the Settings window opens automatically. Get a free key from [Google AI Studio](https://aistudio.google.com/) and paste it in, or edit `.env` directly. Both work, and changes are picked up without a restart.

### Platform notes

- On Windows, use Git Bash (included with Git for Windows) or WSL to run `setup.sh`.
- On macOS and Linux, your normal terminal works.
- **macOS users must build from source** (steps above) — there is no pre-built `.dmg`. Because the app is unsigned, a downloaded build would be blocked by Gatekeeper as "damaged"; running from source avoids that entirely.
- No manual `npm` commands are needed. The script handles everything.

### Setup script options
### Setup options

```bash
./setup.sh --build # Build a distributable for your OS
./setup.sh --ci # Use npm ci instead of npm install
./setup.sh --no-run # Set up only, do not launch
./setup.sh --install-system-deps # Install sox for the microphone (optional)
./setup.sh --skip-whisper # Skip the local Whisper bootstrap
npm run setup -- --build # Build a distributable for your OS
npm run setup -- --ci # Use npm ci instead of npm install
npm run setup -- --no-run # Set up only, do not launch
npm run setup -- --install-system-deps # Install sox for the microphone (optional)
npm run setup -- --skip-whisper # Skip the local Whisper bootstrap
```

## Configuration
Expand Down Expand Up @@ -187,17 +190,25 @@ OpenCluely is under active development. The core is stable and improvements ship
<details>
<summary>Setup issues</summary>

- **setup.sh will not run.** Make sure you are in the project folder (`cd OpenCluely`) and that the script is executable (`chmod +x setup.sh`). On Windows, use Git Bash.
- **Setup stops with exit code 130.** That means Ctrl+C was pressed. Run `./setup.sh` again.
- **`npm run setup` fails.** Make sure you are in the project folder (`cd OpenCluely`) and have Node.js 18+ installed. Check with `node -v`.
- **`./setup.sh` will not run.** Make sure the script is executable (`chmod +x setup.sh`). On Windows, use `npm run setup` instead — it works without Bash.
- **Setup stops with exit code 130.** That means Ctrl+C was pressed. Run `npm run setup` again.
- **Node or npm not found.** Install Node.js 18 or newer from [nodejs.org](https://nodejs.org/), restart the terminal, and retry.

</details>

<details>
<summary>macOS issues</summary>

- **"OpenCluely is damaged and can't be opened."** This is macOS Gatekeeper blocking the unsigned app. Open Terminal and run: `xattr -rd com.apple.quarantine /Applications/OpenCluely.app`, then open the app again.
- **macOS screen capture does not work.** Grant Screen Recording permission under System Settings, Privacy and Security, then relaunch the app.

</details>

<details>
<summary>App issues</summary>

- **Electron will not start or shows a blank window on Linux.** Try `npm run dev`, and make sure X11 or XWayland is available in headless setups.
- **macOS screen capture does not work.** Grant Screen Recording permission under System Settings, Privacy and Security, then relaunch the app.
- **Windows SmartScreen blocks the app.** Click More info, then Run anyway, or use `npm start` during development.
- **Microphone or voice not working.** Voice is optional. For Azure, add valid keys to `.env`. For Whisper, install `openai-whisper`, `ffmpeg`, and `sox`, then set `SPEECH_PROVIDER=whisper`.

Expand Down
Loading