# How to Install vorssaint-utils on macOS: 3 Methods (Homebrew, DMG, Source)

> Install vorssaint-utils on macOS easily with Homebrew, DMG download, or build from source. Get the essential tools for your development workflow quickly and efficiently.

- Repository: [vorssaint/vorssaint-utils](https://github.com/vorssaint/vorssaint-utils)
- Tags: how-to-guide
- Published: 2026-09-13

---

**You can install vorssaint-utils on macOS via Homebrew cask (`brew install --cask vorssaint`), by downloading the signed `.dmg` from GitHub Releases, or by building from source using the [`./build.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/./build.sh) script in the repository.**

Vorssaint-utils is a Swift-based macOS utility that runs entirely locally and provides system-level features through a menu-bar interface. Whether you prefer a one-command installation or need to compile a custom build from the `Sources/` directory, the project supports multiple installation paths tailored to different user needs.

## Installation Prerequisites

Before installing vorssaint-utils, ensure your system meets the baseline requirements. The utility requires **macOS 14 Sonoma or later** and the **Xcode Command-Line Tools** for any build-from-source operations.

If you plan to build manually, the repository relies on the Swift Package Manager manifest defined in [`Package.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Package.swift) to resolve dependencies and compiler settings. Pre-built releases are signed and notarised, so Gatekeeper will not block execution on standard macOS security settings.

## Method 1: Install via Homebrew Cask (Recommended)

The fastest way to install vorssaint-utils is through the official Homebrew cask. This method downloads the pre-built, notarised `.app` bundle and places it directly into `/Applications`.

Run the following command in Terminal:

```bash
brew install --cask vorssaint

```

Homebrew handles the download, verification, and placement automatically. After installation, launch the app from Launchpad or by running `open -a Vorssaint` in Terminal.

## Method 2: Install from Signed Disk Image

If you prefer manual installation or do not use Homebrew, download the latest signed disk image from the [Releases](https://github.com/vorssaint/vorssaint-utils/releases) page. The `.dmg` file contains the notarised `Vorssaint.app` bundle that macOS will open without additional security prompts.

Use these commands to download and install the latest release (example using version 3.1.4):

```bash
curl -L -o vorssaint.dmg \
  https://github.com/vorssaint/vorssaint-utils/releases/download/v3.1.4/vorssaint-3.1.4.dmg
hdiutil attach vorssaint.dmg
cp -R /Volumes/vorssaint/Vorssaint.app /Applications/
hdiutil detach /Volumes/vorssaint

```

Drag-and-drop within the GUI works identically if you prefer a graphical installation.

## Method 3: Build and Install from Source

For developers or users requiring custom builds, clone the repository and use the provided [`build.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/build.sh) script. This path compiles the Swift source code found in [`Sources/Vorssaint/main.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/main.swift) (the application entry point) and assembles the app bundle with proper code signing.

Execute the following commands:

```bash
git clone https://github.com/vorssaint/vorssaint-utils.git
cd vorssaint-utils
./build.sh --install

```

The `--install` flag compiles the project via `swift build`, generates the app icon, creates a signed bundle, and copies the final `.app` into `/Applications`. Without the flag, the script builds the bundle but leaves it in the build directory for manual placement.

### Understanding the Build Pipeline

The build process orchestrates several key components:
- **[`Package.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Package.swift)** – Defines the Swift Package Manager product, target dependencies, and build settings.
- **[`build.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/build.sh)** – Wrapper script that invokes the compiler, processes assets, and handles code signing.
- **[`Sources/Vorssaint/main.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/main.swift)** – The runtime entry point that bootstraps the UI and registers feature modules like `NowPlayingAdapter`.

## First Launch and Permissions

After installation, launch vorssaint-utils from `/Applications` or via `open -a Vorssaint`. The first run triggers macOS permission dialogs depending on which features you enable. Common permission requests include **Accessibility** (for system automation) and **Screen Recording** (for capture features).

Grant these permissions in **System Settings > Privacy & Security** when prompted. The app stores these preferences locally and will not function correctly without the required entitlements.

## How to Uninstall vorssaint-utils

Removal depends on your installation method. For Homebrew users:

```bash
brew uninstall --cask vorssaint

```

For manual installations or source builds, use the repository's dedicated uninstall helper:

```bash
./Tools/uninstall.sh

```

This script (located at [`Tools/uninstall.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/Tools/uninstall.sh)) performs a thorough cleanup: it quits the running application, removes login items, revokes granted permissions from System Settings, and deletes residual preference files.

## Summary

- **Homebrew cask** provides the simplest one-command installation: `brew install --cask vorssaint`.
- **Manual DMG installation** works by downloading the signed release and copying `Vorssaint.app` to `/Applications`.
- **Source builds** require cloning the repository and running `./build.sh --install`, which compiles the Swift code starting from [`Sources/Vorssaint/main.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/main.swift).
- The app requires **macOS 14 Sonoma or later** and appropriate system permissions on first launch.
- Uninstall via `brew uninstall --cask vorssaint` or the [`./Tools/uninstall.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/./Tools/uninstall.sh) helper script.

## Frequently Asked Questions

### Can I install vorssaint-utils on macOS Ventura or earlier?

No. According to the repository documentation and source requirements, vorssaint-utils requires **macOS 14 Sonoma or later**. The Swift code and system APIs used in [`Sources/Vorssaint/main.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/main.swift) depend on frameworks introduced in Sonoma, and earlier macOS versions are not supported.

### Why does macOS block the app when I install from the DMG?

If macOS displays a security warning, you likely downloaded an unsigned version or your Gatekeeper settings are set to "App Store only." Official releases from the GitHub Releases page are signed and notarised. Ensure you download from the official `vorssaint/vorssaint-utils` repository. If issues persist, check [`docs/TROUBLESHOOTING.md`](https://github.com/vorssaint/vorssaint-utils/blob/main/docs/TROUBLESHOOTING.md) in the repository for specific Gatekeeper override instructions.

### Do I need Xcode installed to build from source?

You need the **Xcode Command-Line Tools**, but not the full Xcode IDE. The [`build.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/build.sh) script uses `swift build` (part of the Command-Line Tools) to compile the project defined in [`Package.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Package.swift). Install the tools by running `xcode-select --install` if you haven't already.

### How do I completely remove all traces of vorssaint-utils?

Run the [`./Tools/uninstall.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/./Tools/uninstall.sh) script from the repository root. This utility removes the application bundle, deletes login items, clears stored permissions from macOS Privacy settings, and removes preference files. For Homebrew installations, `brew uninstall --cask vorssaint` removes the app but may leave user preferences; running the uninstall script afterward ensures complete removal.