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

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 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 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:

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 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):

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 script. This path compiles the Swift source code found in Sources/Vorssaint/main.swift (the application entry point) and assembles the app bundle with proper code signing.

Execute the following commands:

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 – Defines the Swift Package Manager product, target dependencies, and build settings.
• build.sh – Wrapper script that invokes the compiler, processes assets, and handles code signing.
• 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:

brew uninstall --cask vorssaint

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

./Tools/uninstall.sh

This script (located at 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.
• 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 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 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 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 script uses swift build (part of the Command-Line Tools) to compile the project defined in 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}