# OrbTorrent

> OrbTorrent is a free, open-source torrent app for the Mac (macOS 26 or later, Apple silicon and Intel). It's a native Swift and SwiftUI app that runs qBittorrent's engine, lives in the menu bar, can download only through a VPN, and holds fake downloads before they arrive. Extensions, written in TypeScript with @orbtorrent/api, check downloads before they start and after they finish. GPL-licensed, with no ads, no account and no tracking: only anonymous counts, without an ID, with its update check.

This website and its docs are open source too. Search engines and AI tools are welcome to use everything on it, including to answer questions and to train on.

Each docs page is also Markdown, at its address plus .md, or at its own address when asked for text/markdown. All of the docs together are in [llms-full.txt](https://orbtorrent.com/llms-full.txt), and the extension docs alone in [docs/extensions/llms-full.txt](https://orbtorrent.com/docs/extensions/llms-full.txt).

## Website

- [Home](https://orbtorrent.com/): what OrbTorrent does, with the features.
- [Download](https://orbtorrent.com/download): the newest version, what it needs, how to install it (or `brew install orbtorrent/tap/orbtorrent`) and uninstall it.
- [Extensions](https://orbtorrent.com/extensions): the Fake Download Check, VirusTotal Scan, and building your own in TypeScript.
- [Switch from Transmission or qBittorrent](https://orbtorrent.com/switch): what comes over when importing.
- [µTorrent for Mac](https://orbtorrent.com/utorrent-for-mac): what happened to µTorrent's Mac app, and how OrbTorrent compares with µTorrent Web.
- [qBittorrent for Mac](https://orbtorrent.com/qbittorrent-for-mac): qBittorrent on the Mac today, and how OrbTorrent runs its engine in a native app.
- [Transmission for Mac](https://orbtorrent.com/transmission-for-mac): what Transmission does well, and what OrbTorrent adds.
- [Privacy](https://orbtorrent.com/privacy): everything the app and the website connect to.
- [FAQ](https://orbtorrent.com/faq): questions and answers.
- [Press kit](https://orbtorrent.com/press): facts, descriptions and images.
- [How OrbTorrent is built](https://orbtorrent.com/how-its-built): the app, qBittorrent's engine, the VPN cut-off and port forwarding, the extension sandbox and signed updates, with excerpts of the code.

## Start

- [OrbTorrent Docs](https://orbtorrent.com/docs.md): How to use OrbTorrent, the free, open-source torrent app made for the Mac, and how to build extensions for it in TypeScript.

## Get started

- [Install OrbTorrent](https://orbtorrent.com/docs/get-started/install.md): Download OrbTorrent for macOS 26 or later, install it from its disk image, and set it up the first time it opens.
- [Your first download](https://orbtorrent.com/docs/get-started/first-download.md): Add a magnet link or a .torrent file to OrbTorrent, choose its files and folder, and find it once it's finished.
- [Magnet links and .torrent files](https://orbtorrent.com/docs/get-started/magnet-links.md): What a magnet link is, how to open one on a Mac, how to choose the app that opens them, and what to do when your browser won't.
- [Switch from Transmission or qBittorrent](https://orbtorrent.com/docs/get-started/switch.md): Bring your downloads and settings over from Transmission or the qBittorrent app in one step, with their folders, file choices, labels and progress.

## Use OrbTorrent

- [The menu bar](https://orbtorrent.com/docs/guides/menu-bar.md): What OrbTorrent's menu bar orb shows, and everything its panel does, from pausing a download to choosing its files.
- [The library window](https://orbtorrent.com/docs/guides/library.md): Find, sort and manage every download in OrbTorrent's window, with its sidebar, search, toolbar and right-click menu.
- [A download's details](https://orbtorrent.com/docs/guides/download-details.md): The inspector shows one download in full, with its files, transfer details, peers, trackers and checks, and the actions you can take on it.
- [Choose files and their order](https://orbtorrent.com/docs/guides/files.md): Download only the files you want, give some priority, and download a torrent's files one after another, or a video in order to watch while it downloads.
- [Checks and held downloads](https://orbtorrent.com/docs/guides/checks.md): How extensions check your downloads, what a held download means, how to set up VirusTotal Scan, and how to install, turn off or remove extensions.
- [Notifications](https://orbtorrent.com/docs/guides/notifications.md): The notifications OrbTorrent sends, what each one's buttons do, and how to turn them on or off.
- [Run a program when a download finishes](https://orbtorrent.com/docs/guides/run-a-program.md): Have OrbTorrent run a script or program of your own when each download finishes, such as one that unpacks it or copies it to another drive.
- [Updates](https://orbtorrent.com/docs/guides/updates.md): How OrbTorrent keeps itself up to date with signed updates, installed while you aren't using it, the settings for checking and installing, and what's new.

## Network and privacy

- [Download only through a VPN](https://orbtorrent.com/docs/guides/vpn.md): A kill switch for your downloads. Tie OrbTorrent to your VPN, so downloading and sharing stop if the VPN drops instead of carrying on without it.
- [Port forwarding](https://orbtorrent.com/docs/guides/port-forwarding.md): Let other peers connect to you, for faster downloads, through your router or your VPN, and check that it's working.
- [Find more peers](https://orbtorrent.com/docs/guides/peers.md): How OrbTorrent finds people to download from, how its public tracker list speeds up slow downloads, and what to try when a download is slow.
- [Speed limits and sharing](https://orbtorrent.com/docs/guides/speed-and-sharing.md): Limit OrbTorrent's download and upload speeds, and stop sharing a finished download once it reaches a ratio.
- [Disk space](https://orbtorrent.com/docs/guides/disk-space.md): How OrbTorrent warns you when a download won't fit, pauses downloads before a disk fills up, and resumes them once there's room.
- [Privacy](https://orbtorrent.com/docs/guides/privacy.md): What other people can see when you download, everything OrbTorrent connects to, and what stays on your Mac.

## Reference

- [Settings](https://orbtorrent.com/docs/reference/settings.md): Every setting in OrbTorrent, what it does, and what it's set to when you first install it.
- [Menus and shortcuts](https://orbtorrent.com/docs/reference/shortcuts.md): Every command in OrbTorrent's menus, with its keyboard shortcut, and the shortcuts in the window and the menu bar panel.
- [Files on your Mac](https://orbtorrent.com/docs/reference/files.md): Where OrbTorrent keeps your library, its settings, the download engine's files, its logs and your extensions, and what's safe to delete.

## Help

- [Troubleshooting](https://orbtorrent.com/docs/help/troubleshooting.md): Fixes for the usual problems with OrbTorrent, from magnet links that don't open and slow downloads to the VPN, the download engine and extensions.
- [Report a problem](https://orbtorrent.com/docs/help/report-a-problem.md): Send a problem report from OrbTorrent with the details that help, open an issue on GitHub, or report a security problem privately.
- [Uninstall OrbTorrent](https://orbtorrent.com/docs/help/uninstall.md): Remove OrbTorrent from your Mac, with or without its library and settings. Your downloaded files stay where they are.

## Build extensions

- [Build extensions](https://orbtorrent.com/docs/extensions.md): Extensions are TypeScript hooks that check a download before it starts, and can hold it, or act on it once it finishes. How they work, and where to start.
- [Your first extension](https://orbtorrent.com/docs/extensions/getting-started.md): Build an extension that holds downloads containing Windows screensavers, test it, run it on a real download in OrbTorrent, and install it.
- [Build with a coding agent](https://orbtorrent.com/docs/extensions/coding-agents.md): Describe an extension, and a coding agent such as Claude Code, Codex or Cursor writes it, tests it and tries it on your downloads, with you deciding each step.

## Build extensions: Concepts

- [Hooks](https://orbtorrent.com/docs/extensions/hooks.md): When beforeStart, afterFinish and afterChecks hooks run, what they receive, how they hold a download, and the limits they run within.
- [Results](https://orbtorrent.com/docs/extensions/results.md): What a hook returns, how each status shows in OrbTorrent, how to mark the files it's about, and how to write results people understand.
- [Extension settings](https://orbtorrent.com/docs/extensions/settings.md): Give an extension settings that OrbTorrent draws, such as an API key kept in the Keychain, read them with getPreferenceValues, and check them with verify.
- [Network requests](https://orbtorrent.com/docs/extensions/network.md): Reach a web service from an extension with fetch, list the hosts it needs, and handle errors, rate limits and redirects.
- [Read and add files](https://orbtorrent.com/docs/extensions/files.md): Fingerprint and upload a finished download's files, and add files such as subtitles next to them with files.save.
- [Storage and progress](https://orbtorrent.com/docs/extensions/storage.md): Keep data between runs with storage, show progress on long checks, read about the extension with environment, and wait without using CPU time.

## Build extensions: Workflow

- [Testing](https://orbtorrent.com/docs/extensions/testing.md): Write JSON tests that run an extension's hooks without OrbTorrent, with the network mocked, file fingerprints and storage set up, and time on a virtual clock.
- [Run and debug](https://orbtorrent.com/docs/extensions/debugging.md): Load an extension into OrbTorrent while you work on it, run a hook on a real download, read its logs, and fix what orb doctor finds.
- [Share and install](https://orbtorrent.com/docs/extensions/sharing.md): Install your extension, package it as an .orbext file anyone can install, release updates, and list it or propose it as an official extension.
- [Security model](https://orbtorrent.com/docs/extensions/security.md): How OrbTorrent runs extensions in a sandbox, what each one can and can't reach, how it keeps secrets, and how the development connection is protected.
- [Examples](https://orbtorrent.com/docs/extensions/examples.md): The templates and official extensions to learn from, a worked example that adds subtitles, and ideas for extensions to build.

## Build extensions: Reference

- [API reference](https://orbtorrent.com/docs/extensions/reference/api.md): Everything @orbtorrent/api provides, with each function's signature, types, limits and errors, and the JavaScript environment extensions run in.
- [The orb command](https://orbtorrent.com/docs/extensions/reference/cli.md): Every orb command and option, what it needs, what it prints, and the JSON it prints with --json, for scripts and coding agents.
- [Manifest](https://orbtorrent.com/docs/extensions/reference/manifest.md): Every field of an extension's package.json, OrbTorrent's rules for each, and what users see from it.
- [Test files](https://orbtorrent.com/docs/extensions/reference/tests.md): Every field of an orb test file, and every expectation it can check.
- [Limits](https://orbtorrent.com/docs/extensions/reference/limits.md): Every limit OrbTorrent puts on an extension, in one place, from time and memory to request sizes and result lengths.
- [Errors and fixes](https://orbtorrent.com/docs/extensions/reference/errors.md): The error messages orb and OrbTorrent give when building, testing, running and installing an extension, what each means, and how to fix it.
- [Changelog](https://orbtorrent.com/docs/extensions/reference/changelog.md): What's changed in each version of @orbtorrent/api, the extension API and the orb command, and which OrbTorrent each needs.

## Contribute

- [How OrbTorrent works](https://orbtorrent.com/docs/contribute/how-it-works.md): How OrbTorrent is put together, from its SwiftUI app and qBittorrent's engine to the sandboxed extension host and signed updates.
- [Contribute to OrbTorrent](https://orbtorrent.com/docs/contribute.md): How to report problems, suggest features, build OrbTorrent from source, and send a change, with the project's layout and the rules for pull requests.

## Optional

- [Source code](https://github.com/orbtorrent/OrbTorrent): the app, the extension SDK, the official extensions and this website.
- [@orbtorrent/api on npm](https://www.npmjs.com/package/@orbtorrent/api): the extension API and the `orb` command-line tool.
- [Agent Skill](https://orbtorrent.com/.well-known/agent-skills/index.json): for coding agents building an extension, also [on GitHub](https://github.com/orbtorrent/OrbTorrent/tree/main/skills/build-orbtorrent-extension).