Run and debug

Tests catch most problems without OrbTorrent. To see an extension work for real, load it into OrbTorrent and run it on your downloads.

Get OrbTorrent ready

orb dev and orb run talk to OrbTorrent on your Mac. They need:

1. OrbTorrent open.
2. Allow development extensions on: Extensions, at the bottom of OrbTorrent’s sidebar, then the Develop tab. Only you can turn it on.
3. Your folder allowed. The first time a folder loads, OrbTorrent asks whether to load it. Allow it.

npx orb doctor checks all of this, and says what’s missing:

npx orb doctor

✓ Node.js 24.11.1
✓ No Screensavers (no-screensavers), with @orbtorrent/api 1.0.3
✓ Built into dist/
✗ OrbTorrent is open, but doesn't allow development extensions.
  → Ask the user to turn on “Allow development extensions” in OrbTorrent: Extensions, at the bottom of the sidebar, then the Develop tab. Only the user can. If the switch at the top of the Installed tab is off, extensions are off altogether, and that needs turning on first.

1 thing to fix.

A ✓ is fine, a ✗ needs fixing, and a · is information. orb doctor lists everything it checks.

Work with orb dev

npm run dev

Output

✓ Loaded No Screensavers into OrbTorrent.
Rebuilding on every save. Press Control-C to stop; the extension stays in OrbTorrent.

orb dev loads the extension into OrbTorrent, then rebuilds and reloads it every time you save a file. It also prints what the extension does as it happens, on any download:

Output

[check · Ocean Life (2026) 1080p] ✗ failed: Contains a screensaver, which is a Windows program: Play Me.scr
✓ Rebuilt and reloaded 14:02:31

Each line says which hook and which download, then the check’s result, its progress, or what it logged.

A loaded extension runs on new downloads like an installed one, and shows on the Develop tab under In Development, with Reload and Show in Finder. It stays loaded after you stop orb dev, until you remove it from its page or install it for good.

Developing an official extension

A development copy of an official extension, such as the Fake Download Check, stands in for the official one while it’s loaded, marked Development copy. Remove it from its page, and the official one takes its place again.

Run a hook on a download

To try a hook on one of your downloads, list them, then run it:

npx orb downloads
npx orb run check --download "Big Buck Bunny"

npx orb downloads

finished   276.0 MB  Big Buck Bunny  dd8255ecdc7ca55fb0bbf81323d87062db1f6d1c
42%          6.0 GB  ubuntu-26.04-desktop-amd64.iso  0d6a0b7f4b3e2e4a8b9c1d2e3f405162738495a6

Run a hook on one with `npx orb run <hook> --download "<name or info hash>"`. An afterFinish hook needs a finished one, and an afterChecks hook one that's finished or held.

• --download takes part of a download’s name, or its whole info hash. If it matches more than one, orb run lists them, so you can be more specific.
• The hook’s name can be left out when the extension has only one.
• An afterFinish hook needs a finished download, since it reads files that are all there. An afterChecks hook needs one that’s finished or held by a check, and gets the checks’ results as they are.
• Run by hand, every file is new, so isNew is true for each finished file.

orb run builds the extension, loads it, runs the hook inside OrbTorrent, and prints what it logged and returned:

Output

✓ passed: No screensavers

The result also shows in the download’s Checks tab, as a real check would.

Logs

Anything the extension writes with console.log, console.warn, console.error and the rest goes to its log:

• In OrbTorrent, on the extension’s page, under Logs, with Clear and Show Log File. The file is ~/Library/Application Support/OrbTorrent/Extensions/Logs/<name>.log.
• In your terminal, while orb dev or orb run is running.
• In tests, under a failing test’s output, and in orb test --json’s logs.

When a hook throws, its stack trace goes in the log too. OrbTorrent hides password settings in logs.

When a check didn’t finish

The Checks tab says why, and so does orb run:

It says	Because	Try
Didn’t finish: the error’s message	The hook threw.	Read the stack trace in its log.
Didn’t finish: it took longer than 15 s	Over the time limit.	Fewer or faster requests before a download starts, or move the work to afterFinish.
Didn’t finish: it kept the processor busy for over 10 s	Over the CPU limit.	Do less work in loops. Waiting with sleep doesn’t count.
Didn’t finish: it used more than 512 MB of memory	Over the memory limit.	Don’t hold large responses or lists.
Didn’t finish: It returned something that isn’t a result	It returned no status or summary.	Return { status, summary }.

Limits has every limit, and Errors and fixes every error message.

OrbTorrent Dev

If you build OrbTorrent itself, put ORB_APP=dev before orb commands to reach OrbTorrent Dev instead:

ORB_APP=dev npx orb run check --download "Big Buck Bunny"