capture agent

Desktop capture agent

rdownloader-capture is a separate, per-user desktop program. It catches links where they appear — Click'n'Load buttons, the clipboard, a double-clicked .nzb, link container or torrent, a file dropped on its desktop shortcut — and hands them to the service's LinkGrabber.

It is optional. The service works fine without it; you just paste links yourself.

It is a desktop program. The Docker image does not contain it. On a NAS or a server, use the browser extension instead, or run the agent on your desktop pointed at the remote service.

Pairing

The agent needs a capture token, issued in the web interface under Settings → Clients & API → Desktop (or during the setup wizard). It is shown exactly once. Expires sets how long it lasts — Never, the default, or 7, 30, 90 or 365 days; an expired token is refused and stays listed until you revoke it.

rdownloader-capture configure --token-stdin

--token-stdin reads the token from standard input and is the recommended way: an argument is readable by every local user through ps or the task manager and lands in the shell history. --token <TOKEN> works too and is what the pairing card's copyable command uses.

For a remote service, name it too:

rdownloader-capture configure --service https://nas.example --token-stdin

A non-loopback address must be https. The capture token is a long-lived credential sent with every request, so pairing over plain HTTP to another machine is refused unless you pass --allow-insecure-service. An existing plain-HTTP pairing to another machine is named in a warning on every start until it is paired again over https.

The token is stored in the operating-system keyring, with a user-private 0600 file fallback on Unix. The service address goes into capture.json in the per-user configuration directory.

A capture token is not an API token. It may push links into the LinkGrabber, read one narrow event stream and read and switch the agent's own settings (the clipboard pause and the shortcuts below) — nothing else. It cannot read download paths, change any other setting, or reach the MCP endpoint, and it cannot be minted as an API token. See Accounts, sessions and permissions.

May control the queue. Tick this box on the pairing card to let the agent pause and start the whole queue from its tray, add everything from the LinkGrabber, and step aside for games (all below). It is off unless you tick it, it is offered for the desktop agent only, and it adds exactly that: pausing everything, for a while or until resumed, resuming it, sending the LinkGrabber's contents to the downloads, and the game-mode hold — no single download, no reordering, no reading the queue. To give an agent that is already paired the right, pair it again with the box ticked; the list of paired connections shows capture:queue beside the ones that have it.

May install server updates. A second box on the pairing card, also off unless you tick it, lets the agent install rDownloader's own update from its tray (see Installing the server's update) and restart rDownloader when a restart is pending (see Restarting the server). Without it, the update entry only opens the update page in the browser, and Restart server is not shown.

Running it

rdownloader-capture run

Or let it start at login:

rdownloader-capture autostart install

autostart remove disables future login starts without stopping the process that is running. Linux uses systemd user units, macOS LaunchAgents, Windows a windowless per-user launcher.

The portable launchers (start-rdownloader.sh, .bat, .command) start the agent alongside the service; pass capture to start only the agent.

With Homebrew

Installed through Homebrew, the agent's login start is a formula of its own:

brew install degoya/rdownloader/rdownloader-capture
rdownloader-capture configure --token-stdin
brew services start rdownloader-capture

It runs the rdownloader-capture of the rdownloader formula, so brew upgrade keeps it current. On macOS it is a LaunchAgent in your login session, so the tray icon appears; the tray's Quit stays quit until the next login or brew services restart rdownloader-capture, while a failure restarts it. The log is $(brew --prefix)/var/log/rdownloader-capture.log. Use this instead of rdownloader-capture autostart install, which would start a second agent that finds port 9666 taken.

Keeping it up to date

Where the agent runs beside rDownloader — the same folder, the installer, a Linux package — the service's update replaces both programs, and the agent restarts as the new version by itself within half a minute. Nothing else to do.

An agent installed without rDownloader — the service on a NAS, in Docker or on another computer — updates itself from 1.21 on:

• A minute after it starts, and then once a day, it asks for a newer version on the channel your rDownloader reads (stable when it cannot tell). It accepts only a release signed with rDownloader's update key, and never offers a version older than the one it runs.
• The tray menu then shows Install update to 1.21.0. Choose it, and the agent downloads its own archive, checks it against the signed release, replaces its program files and restarts as the new version. If the new version does not start within two minutes, the previous one is put back and runs again.
• Without a tray (Linux), or from a terminal: rdownloader-capture update. It checks, installs and says how it ended; rdownloader-capture update --check only says what is offered.
• An agent installed with Homebrew's rdownloader-capture formula is told to run brew upgrade rdownloader-capture instead.
• Settings → System → Updates in rDownloader shows when a connected agent offers itself an update.

To switch the agent's own check off, or back on:

rdownloader-capture update --auto-check off

rDownloader cannot make the agent install anything. It can only ask once the agent allows it — rdownloader-capture update --allow-remote on, off by default — and the agent then installs only the version it found itself.

Installing by itself. A portable agent installed without rDownloader can also install an update the moment its check finds one, with the same verification and roll-back: tick Install updates automatically in its tray menu, or run

rdownloader-capture update --auto-install on

(off switches it back). It is off by default and kept across restarts. Beside the service the item is not shown: there rDownloader's own Install updates automatically setting decides for both programs — see Updates.

What it captures

Click'n'Load 2

The agent serves a JDownloader-compatible Click'n'Load endpoint on 127.0.0.1:9666 and [::1]:9666, loopback only. A site's "Click'n'Load" button therefore works exactly as it would with JDownloader running.

If port 9666 is already taken — a second capture agent from autostart, or JDownloader itself — the agent reports it and exits with code 11; decide which program should have the port. A bind to only one of the two addresses is reported, not counted as success.

Only one agent runs per user account. A second one started while the first runs waits up to ten seconds — long enough for the restart after an update, where the new agent starts before the old one has ended — and then says the agent is already running and exits with code 11 as well.

Loopback is not a boundary against a browser: every page open in your browser can reach 127.0.0.1:9666. So the port decides per route who may call it.

• The JDownloader-compatible /flash* routes allow cross-origin calls, because a hoster's page calls them from its own origin.
• The port takes no NZB file. A double-clicked .nzb and an rdownloader:// link go to the rDownloader service directly, with the agent's pairing token — never through the port, which another account on the same machine could hold while no agent runs.
• A refusal answers with a stable code; the detail stays in the log. The answer never says why a payload failed to decrypt.
• Each route has its own size limit, enforced before the body is decoded.
• At most 30 hand-overs a minute are accepted; past that a page gets 429 with the code cnl_rate_limited and nothing reaches the LinkGrabber. A package name is cut to 200 characters, and a password longer than 1024 characters is refused.
• The preflight answer names the headers Content-Type and X-Referer — some hoster pages send their address in X-Referer and the browser drops the request otherwise; the agent never reads it — and says Access-Control-Allow-Private-Network: true, which Chrome asks for before a public page may call 127.0.0.1. Both open the JDownloader-compatible routes only, which any page may reach anyway; that is what Click'n'Load is.

The clipboard

HTTP(S) links copied to the clipboard are picked up and offered to the LinkGrabber. Enabled by default; --clipboard=false turns it off.

The native clipboard is used on Windows, macOS, X11 and supported Wayland compositors. A pure Wayland session needs the data-control protocol; where the compositor does not provide it, Click'n'Load keeps working and the limitation is written to the capture log.

What a password manager marks as concealed is left alone: neither handed over nor written to the log. The agent honours the marks password managers set on each platform — ExcludeClipboardContentFromMonitorProcessing and CanIncludeInClipboardHistory on Windows, org.nspasteboard.ConcealedType and TransientType on macOS, x-kde-passwordManagerHint under X11 and Wayland. Password managers such as KeePassXC set them for a copied password; one that sets none of them is not recognised.

Who gets the token

Before the agent sends its token anywhere, it asks the service address who answers there. Only rDownloader gets the token. Any other program listening on that address — another account's server on a shared machine, a development server, a mistyped port — gets nothing, and the agent writes it to its log; a double-clicked .nzb or an rdownloader:// link says so in a notification. The check tells rDownloader apart from other programs, not from a program built to pass for it.

Pausing clipboard watching

When you copy links you do not want downloaded, pause the watching:

• the tray's Pause clipboard watching entry (ticked while paused),
• its keyboard shortcut (see below),
• the switch on Settings → Clients & API → Desktop, or the MCP tool update_capture_agent_settings,
• on a desktop without a tray: rdownloader-capture pause, resume and status.

Only the clipboard pauses. Click'n'Load, the browser extension and rdownloader:// links keep working, because you trigger those on purpose. While paused the agent does not read the clipboard at all, and links copied during the pause are not delivered when you switch it back on — only what you copy afterwards. The tray icon turns grey and the status line and tooltip end on capture paused.

The service keeps the setting, so every switch — tray, settings page, command — is the same one, and a change made in the web interface reaches the running agent within five seconds. The agent keeps a copy, so it starts paused after a restart even when the service is not up yet.

Handing the clipboard over once

Hand over clipboard now reads the clipboard once and delivers its links, also while watching is paused — for the one link you do want. It is in the tray menu, has its own shortcut, and on any desktop rdownloader-capture send-clipboard does the same. A notification says how many links were handed over, or No link found on the clipboard.

Files handed to the agent

rdownloader-capture association install

Double-clicking an .nzb file then imports it. The link containers .dlc, .ccf, .rsdf, .rdlinks and .crawljob and .torrent files are offered too, without taking another program's default: each gets an "Import into rDownloader" entry in its right-click menu, and the agent appears in its Open with list. The NZB gets the same entry, whichever application is its default handler:

• Windows 11 — the entry appears under Show more options (Shift + F10), not at the top level.
• Linux — the agent's desktop entry names all seven types, so it appears in file managers' Open With list for each.
• macOS — there is no Finder context-menu item. Use Open With and pick rDownloader Capture.app, which ships in the macOS archive and must stay next to rdownloader-capture; it never becomes the default for these types.

association remove takes all of it back.

Windows: a drop shortcut and Send to.

rdownloader-capture drop-shortcut install   # "Add to rDownloader" on the desktop
rdownloader-capture send-to install         # "rDownloader" under Send to

Files dropped on Add to rDownloader, or sent with right-click → Send to → rDownloader, are handed over like a double-clicked one; remove takes either back. The Windows installer runs all three commands for you when you pass ASSOCIATION=1, DROPSHORTCUT=1 or SENDTO=1, and removes all three when it uninstalls; see Installation.

However they arrive — a double-click, a drop, Send to — several files at once end in one notification with the count: an NZB lands as an NZB import, a container goes through the LinkGrabber's container import, a torrent becomes a LinkGrabber package. A file of any other type is refused and named in that notification. Metalink files (.metalink, .meta4) are not taken this way; paste their content into Add links instead.

rdownloader:// links

The agent can register as the handler for rdownloader:// addresses, so a page or a script can hand links over with one click:

rdownloader-capture scheme install     # Windows and Linux
rdownloader-capture scheme remove

Two forms are accepted:

Address	Does
rdownloader://add?url=<link>	Adds one link. Repeatable; magnets allowed. urls= takes a newline-separated list.
rdownloader://open?path=<absolute path>	Imports a local .nzb

A scheme handler is reachable from any web page, so everything else is refused:

• no file:, javascript: or data: links,
• no relative paths, no .. and no network share,
• no .torrent with open — only .nzb files are imported this way,
• at most 50 links and 8,192 characters.

What it accepts goes into the same LinkGrabber review the clipboard and the file association use.

macOS is not supported — a bare executable cannot claim a URL scheme there; scheme install says so.

What it does not do

It does not answer widget captchas (reCAPTCHA, hCaptcha, Turnstile); answering one by hand goes through the browser extension.

Tray icon and notifications

On Windows and macOS, run shows a tray or menu-bar icon with the paired service, a title line, two status lines, Open rDownloader, About rDownloader and Quit. The icon carries a badge while work is going on, and "Open" is enabled only when there is something to open. On macOS the agent stays out of the Dock.

The menu opens on a title line — the rDownloader mark and rDownloader v… with the agent's version — that cannot be chosen, with a separator below it. About rDownloader, beside Open rDownloader, opens Settings → About rDownloader of the paired rDownloader in the browser; like Open, it is greyed out while the server does not answer.

Two status lines follow: the first names the agent's version and address with what the queue is doing, the second the server — Server v1.24.0 — running, or Server — not reachable without a version while it does not answer. The server's version is shown only when the address answers as rDownloader. The tooltip keeps one line naming the agent and the server's state.

Below them the menu lists the queue controls, named like the Start all / Pause all control in the web interface. Each is enabled while it would do something:

• Start all while a timed pause holds or downloads are paused: it ends the timed pause, or starts the paused downloads again. Failed downloads stay as they are — restart those in the web interface.
• Pause all while anything downloads or waits.
• Pause for 30 minutes and Pause for 1 hour while no timed pause holds — the same timed pause the web interface sets, which also keeps new links waiting until it ends.

While a timed pause holds, the status line starts with paused until 18:30.

Beside them, two entries empty the LinkGrabber the way e and w do in the web interface:

• Add all from LinkGrabber — every package with a link checked online and every imported NZB goes to the downloads and starts.
• Add all from LinkGrabber paused — the same, added paused.

A package or NZB that holds something already added stays in the LinkGrabber: the web interface asks about those, the tray cannot. A desktop notification says what happened — 5 links and 1 NZB added to the downloads, or The LinkGrabber has nothing to add.

The controls work only for an agent paired with May control the queue ticked. An agent paired without it shows them greyed out with Pair again to control the queue: pair it again with the box ticked to use them.

Pause while gaming is a check item that switches game mode on and off without opening the web interface; it is the same switch as on the settings page. It is greyed out with (set up in Settings) while no program and no full screen is set to watch for, and for an agent paired without May control the queue.

Install updates automatically is a check item of an agent installed without rDownloader only; see Keeping it up to date. Beside the service it is not shown.

An icon that cannot be created — in a remote session, for instance — is logged as a warning and the agent keeps running headless.

--no-tray (or RDOWNLOADER_NO_TRAY=1) forces headless mode. Without the tray there are no keyboard shortcuts on Windows and macOS: the tray's event loop is what receives them.

Linux is always headless; the systemd user unit from autostart install provides the status instead.

Installing the server's update

While rDownloader is offered a newer version, the menu shows Install server update 1.25.0 (with the offered version):

• Paired with May install server updates — choosing it installs the update, the same install as Settings → System → Updates with its backup, checks and roll-back. A notification says it started, the server line reads Server — updating to v1.25.0…, and a second notification tells how it ended, also when the update restarted the agent. While downloads are running, the entry asks first: choose it again within two minutes to go ahead; they continue after the restart.
• Paired without it — the entry opens the update page in the browser.
• An installation a package manager or Docker updates shows its update command, greyed out, and installs nothing.

Restarting the server

When something waits for rDownloader's next start — a plugin installed or updated, see Restarting when needed — the server line ends in restart pending. An agent paired with May install server updates then shows Restart server, greyed out while an update is being installed or a restart has already begun. Choosing it restarts rDownloader the way Restart now in the web interface does, and a notification says that it restarts and how it comes back. While downloads are running, the entry asks first: choose it again within two minutes to go ahead; they continue after the restart. An agent paired without the right does not show the entry; its shortcut only says to pair again.

Keyboard shortcuts

Every entry of the tray menu that you can choose can have a system-wide keyboard shortcut, so you can pause, resume or hand the clipboard over without opening the menu. Sixteen commands, seven with a shortcut by default; the others have none until you give them one. The menu shows each shortcut beside its entry. Only the title and status lines have none, since there is nothing to choose.

Command	Windows and Linux	macOS
Open rDownloader	Ctrl+Alt+O	Cmd+Option+O
Start all	Ctrl+Alt+G	Cmd+Option+G
Pause all	Ctrl+Alt+P	Cmd+Option+P
Pause for 30 minutes	Ctrl+Alt+K	Cmd+Option+K
Pause for 1 hour	Ctrl+Alt+Shift+K	Cmd+Option+Shift+K
Pause clipboard watching	Ctrl+Alt+Z	Cmd+Option+Z
Hand over clipboard now	Ctrl+Alt+V	Cmd+Option+V
Pause while gaming	none	none
Install server update	none	none
Install updates automatically	none	none
Quit	none	none
Add all from LinkGrabber	none	none
Add all from LinkGrabber paused	none	none
Install update (the agent's own)	none	none
Restart server	none	none
About rDownloader	none	none

The commands without a default can be given a shortcut like the others; Quit has none by default so that a stray key press does not end the agent. A shortcut does what the menu entry would, under the same rules: where the entry would be greyed out or refused, the shortcut does nothing and says why. The two LinkGrabber shortcuts of an agent paired without May control the queue, and Install update while the agent has no update of its own to install — beside the service, or with nothing offered — tell you so in a desktop notification.

A tray entry added in a later version comes with its command as well, so it can always have a shortcut.

Change them on Settings → Clients & API → Desktop: press Record beside a command and then the combination; Reset brings the default back, No shortcut removes it. The running agent takes the change within a few seconds, without a restart. MCP sets them with update_capture_agent_settings, and rdownloader-capture status lists them.

A combination needs two of Ctrl, Alt/Option and Win/Cmd (Shift may come on top), so it cannot take away a program's own shortcut such as copy and paste. Combinations the system already uses (such as Ctrl+Alt+Delete) and one that another command has are refused when you save. If another program already holds a combination, the agent reports it and the settings page names the command — pick another one there.

On Windows, AltGr is Ctrl+Alt. The defaults avoid the AltGr characters of German, French and Spanish keyboards; on a layout that types more letters with AltGr (Polish, Czech), change a default that hides a character you need.

Linux: shortcuts work in an X11 session only. Wayland gives no program a system-wide shortcut; there the agent registers none and the settings page says so — use rdownloader-capture pause, resume and send-clipboard, for example from your desktop's own shortcut settings.

Desktop notifications

The agent raises a native desktop notification when links arrive in the LinkGrabber, one per import — so a handoff is visible without a browser tab open. The event stream it reads carries only intake events and a bare captcha count, so the token cannot see download paths or credential changes. After a reconnect, imports that arrived meanwhile are still announced. While the agent is connected, an open rDownloader tab leaves this notice to it, so links that arrive are announced once. Links the browser extension hands over are announced by the extension, so the agent raises nothing for them; its own Click'n'Load and the files you open with it keep their notification. During quiet hours the agent raises none; what arrived meanwhile is announced together once they end.

Linux uses the freedesktop D-Bus interface. On Windows, run association install so the notification is attributed to rDownloader rather than PowerShell. A desktop with no notification daemon is a log warning and nothing more.

--no-notifications (or RDOWNLOADER_NO_NOTIFICATIONS=1) turns it off.

The notification about links arriving in the LinkGrabber speaks the desktop's language when it is German, English, French or Spanish, and English otherwise: the language your session sets, or, when it sets none — as on Windows and for an agent macOS starts at login — the system's preferred language. The tray menu and the agent's other notifications are English only.

Game mode

The agent can step aside while you play, watch a film or present. Set it under Settings → Clients & API → Desktop, card Step aside for games:

• While a program is full screen — games, videos and presentations in full screen. Windows only: macOS cannot tell without the screen-recording permission.
• While these programs run — process names such as game.exe or obs64, without a path; capitals and the .exe ending do not matter. Windows and macOS.
• What the agent does then — Pause the queue (running and waiting downloads stop and start again afterwards) or Switch on a bandwidth profile (downloads go on at the profile's limits; the schedule decides again afterwards). The profile has to exist first, under Bandwidth.

Press Save game mode; the running agent takes it over within a few seconds. Game mode switched on at the top of the card is the same switch as Pause while gaming in the tray: switched off, the programs are kept for next time, and a pause the agent set ends at once. The switch survives a restart of the agent. An assistant sets the same over MCP with update_capture_agent_settings.

The agent holds the pause or the profile for 15 minutes at a time and renews it while the program runs, so an agent that crashed or a machine that went to sleep leaves nothing behind for longer. It lifts only what it set itself: it does not take over a pause or a profile somebody else switched on, and a pause of its own that you resume in between stays resumed until the game is over. Game mode needs the agent paired with May control the queue. Linux has no game mode.

Commands and flags

Command	Does
run	Run the agent
configure --service URL --token-stdin	Pair with a service
open <PATH>...	Hand one or several files over — NZBs, link containers and torrents; what the file association, the drop shortcut and Send to run
handle <URL>	Handle one rdownloader:// address
scheme install / remove	URL-scheme handler registration
association install / remove	File association for .nzb, the link containers and .torrent
drop-shortcut install / remove	The Add to rDownloader shortcut on the desktop (Windows)
send-to install / remove	rDownloader under Send to (Windows)
autostart install / remove	Start at login
pause / resume	Pause or resume clipboard watching
status	Whether clipboard watching is paused, and the shortcuts
send-clipboard	Hand the clipboard's links over once, also while paused
update	Check for a newer agent and install it — only for an agent installed without rDownloader (above); --check only looks
update --auto-check on|off, --allow-remote on|off	Switch the agent's own daily check, and whether rDownloader may ask it to install
update --auto-install on|off	Whether the agent installs a found update by itself

Flags for run: --service (RDOWNLOADER_SERVICE; https, or plain http on this machine only — a plain-http address elsewhere is accepted only from configure --allow-insecure-service), --cnl-listen (repeatable, defaulting to 127.0.0.1:9666 and [::1]:9666), --clipboard, --no-notifications (RDOWNLOADER_NO_NOTIFICATIONS), --no-tray (RDOWNLOADER_NO_TRAY).

Flags for configure: --service, --token, --token-stdin, --allow-insecure-service.

pause, resume, status, send-clipboard, open and handle take --service like run.

The token is never a command-line argument of these commands: every account on the machine can read a command line. It comes from the keyring, the private fallback file, or the environment variable RDOWNLOADER_CAPTURE_TOKEN.

Exit codes

Code	Meaning
0	Fine
10	Not paired yet
11	Already running — another agent of this account, or JDownloader holding the Click'n'Load port
1	A real failure

10 and 11 are reported by the portable launchers as outcomes, not as a failed start.

Related pages

• Browser extension — the alternative for NAS and Docker
• The LinkGrabber — where everything it captures lands
• First run — issuing the pairing token
• Accounts, sessions and permissions