Harbor: a native macOS download manager for links, magnets and torrents

A native shell around download engines rather than a reimplementation

Harbor is described as a beautiful, fully native macOS download manager built for real Mac workflows, and the reason it can be both is a specific architectural choice: a polished native SwiftUI interface combined with pragmatic download engine separation.

The application handles direct HTTP and HTTPS downloads, public media links, magnet links and .torrent files. The engine separation means the download logic is not entangled with the interface, which is what allows the app to feel Mac-native while still covering a job that most Mac download managers delegate to aria2c or to a Python tool. The repository topics list aria2c and yt-dlp alongside Swift, SwiftUI, macOS and torrent-client-desktop.

The design position is stated without hedging in the header: free, local-first, privacy-friendly, and designed to feel like a proper Mac app from day one, with no accounts, no sign-in, no hosted backend and no subscription mechanics. That is a real constraint on the feature set, because a hosted backend is how most of these products implement things like cross-device queue state, and here there is nothing to sync to.

The interface description gives a sense of the scope: sidebar navigation, a unified toolbar, a detail inspector, Quick Look previews for completed downloads, Finder reveal and open-file actions, and pause, resume, retry, cancel and history flows. There is a batch add feature where you paste many links, choose one folder and queue them together, and a queue that persists across launches.

The download controls are more granular than the usual. Traffic profiles cover Unlimited, Balanced, Quiet and Custom download behaviour, and there are global and per-download speed controls. Torrent handling goes further than most: watch folders, seeding controls and share-ratio limits, plus a torrent preview that lets you inspect the file list and choose what to download before you start.

Installing it, and the two handoff paths into the app

There are two ways to install Harbor and two ways to get a link into it.

The install is either Homebrew:

brew tap thsnkhn/harbor
brew install --cask harbor

or the DMG, which you download from the latest release and then drag Harbor.app into Applications. Once installed, the app can check for new versions from the app menu and update through its built-in Sparkle updater, so the Homebrew route does not have to be your only update mechanism.

The URL handoff is the part worth understanding, because it is what makes Harbor scriptable and what the Safari extension relies on. Browser extensions, command-line tools and automations can open Harbor with an HTTP or HTTPS download URL using a custom scheme:

harbor://download?url=https%3A%2F%2Fexample.com%2Ffile.zip

The download URL has to be percent-encoded as the url query value. You can test the handoff on macOS with the open command:

open 'harbor://download?url=https%3A%2F%2Fexample.com%2Ffile.zip'

Harbor then opens its Add Download sheet with the link filled in, and the user confirms the destination and starts the download. That last point is deliberate. The handoff does not start a download, it pre-fills a form, so a script cannot silently begin fetching things into a folder of the app's choosing without a person seeing it.

The macOS requirement is strict enough to be worth stating plainly. The platform badge says macOS 15.6+, and there is a SwiftUI application target, so this is not something you can run on an older Mac or on a non-Apple platform.

The Safari extension intercepts clicks, which is not the same as downloads

Harbor.app includes a Safari extension that hands links to Harbor through the harbor:// and magnet: URL schemes, and the README is refreshingly honest about what it can and cannot do.

The extension offers three things. Download with Harbor is a right-click menu item on any link. Click interception is on by default and handles a link with a download attribute, a magnet: link, or a link whose path ends in a download extension such as .dmg, .zip, .mp4 and .torrent, and the extension list is the DOWNLOAD_EXTENSIONS constant in HarborSafariExtension/content.js. Holding Option while clicking lets Safari handle the download instead. The toolbar popup toggles interception on or off, turns it off for the current site only, or sends the current page to Harbor, and Harbor then offers yt-dlp for pages it recognises, such as YouTube.

The limitation is stated in one sentence and it is the important one: Safari has no downloads API for extensions, so this is an approximation, the extension sees link clicks rather than downloads, and it misses downloads started by scripts, form posts and redirects. When it misses one, Safari downloads the file as usual.

Two further details. Click interception also runs in embedded frames, and the per-site toggle applies to the tab's website including links in frames from other websites. Until the extension has loaded its saved settings and identified the tab's website, clicks stay in Safari.

Enabling it takes three steps. In Harbor, open Settings, then Experimental, and click Enable in Safari. Then turn Harbor on in Safari's Extensions settings. Finally, select Harbor and set Other websites to Allow, without which Safari does not run click interception at all. Safari then asks whether to allow each site to open Harbor.app, and choosing Always Allow stops the prompt for that site, though it asks again for each new site, and on bare IP addresses such as 127.0.0.1 it asks every time.

Local builds, code signing, and the unsigned extension problem

Building from source has a wrinkle that most macOS apps never have to deal with, and the documentation covers it in detail.

The script script/build_and_run.sh signs Harbor and its extension with the project's Developer ID identity by default. Setting CODE_SIGN_IDENTITY uses another identity, and setting CODE_SIGNING_ALLOWED=NO builds without signing at all. To prepare a local build for notarization, CODE_SIGN_INJECT_BASE_ENTITLEMENTS=NO omits debugger-only entitlements.

The reason this matters is that Safari loads unsigned extensions only when you allow them, and the allowance is not sticky. In Safari you turn on Settings, then Advanced, then Show features for web developers, and in Settings, then Developer, you turn on Allow unsigned extensions, which Safari turns off each time it quits. The README also states plainly that the extension must be signed and sandboxed, or macOS ignores it.

For a build with no signing identity, the workaround is to sign ad hoc and register it, which starts from the built app path:

APP=build/HarborDerivedData/Build/Products/Debug/Harbor.app

The registration step that follows involves writing a plist, and the README text for it is cut off in the source available, so the exact command is not something to guess at.

The build directory layout gives a sense of the project's shape. There is Harbor.xcodeproj, a Harbor/ directory for the app, HarborSafariExtension/ for the extension, HarborTests/ and HarborUITests/ for the test targets, three separate UI test plans as .xctestplan files named HarborUILiveCanary, HarborUIOffline and HarborUISystem, a Vendor/ directory for vendored dependencies, and Tools/, Scripts/ and script/ directories. There is also a docs/ directory, an AGENTS.md file and a .codex/ directory, both of which are instructions for coding agents rather than for human contributors.

GPL-3.0, active maintenance, and what a download manager still cannot promise

The licence is the most consequential fact for anyone thinking about contributing or shipping a fork.

Harbor is free and open source under GPL-3.0. For a desktop app that most people install rather than redistribute, the practical effect is small. If you modify Harbor and distribute the modified app, the GPL obligations reach you, which is a heavier requirement than the MIT licence most download managers use, and worth checking with your own legal review before you fork it for commercial distribution.

Maintenance is clearly active. The last push to the repository was on 2026-10-20, the repository carries an actively maintained badge, and the release history shows v1.8.6 on 2026-10-20, v1.8.3 on 2026-10-11 and v1.8.2 on 2026-10-10. A patch release and a minor release in the same week is a project that ships when it fixes something. The homepage is a GitHub Pages site at thsnkhn.github.io/harbor.

What the project does not claim is worth naming, because a download manager sits close to the edge of what is legitimate. The YouTube integration is offered by the Safari extension popup, which offers yt-dlp for pages it recognises, and the torrent support includes seeding and share-ratio controls, which are features of a peer-to-peer client rather than of a web scraper. Nothing in the documentation describes bypassing paywalls, DRM or authentication, and the public media wording is careful, saying public media downloads with previews and video or audio format selection.

What it also does not promise is reliability against every site. The Safari extension misses script started downloads, form posts and redirects, and the torrent preview exists precisely because a magnet link can resolve to something you did not want. Those are the two places where the honest expectation is that Harbor handles most links rather than all of them.

Editorial conclusion

Harbor suits a Mac user who wants a download manager that behaves like a native app rather than a wrapper around a command line tool, and the separation of the SwiftUI interface from the download engine is what makes that possible. It does not suit you if you need a Linux or Windows client, since it is macOS only and requires 15.6 or later, and it does not suit anyone who wants a hosted component, because there is deliberately no account and no backend. Before you install it, read the Safari extension section, since click interception is an approximation that misses script started downloads, form posts and redirects, and set up the unsigned extension setting only if you are prepared to re-enable it each time Safari quits.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. thsnkhn/harbor on GitHub