Repository navigation
first run
The first time you open http://127.0.0.1:8710/, rDownloader shows the Setup assistant: six steps that get the service into a usable state. Only two of them have to be answered — the password and at least one storage root. Everything else can be skipped and configured later under Settings.
You can reopen the assistant at any time; it is offered again from the System settings page.
Set the local administrator password. The service stays bound to loopback by default.
The password must be at least 10 characters. It protects the web interface, the REST API and the MCP endpoint.
There is exactly one administrator account. rDownloader has no multi-user model: separate identities for scripts and assistants are handled by API tokens, not by extra logins.
On a machine you alone use, the login can be switched off later with Disable admin login under Settings → Security → Sign-in. This applies to this computer only: a request from this machine's loopback address that no proxy forwarded gets in without the password; every other request — another computer in your network, a reverse proxy, a Docker port mapping — still has to sign in. In a container the login is therefore always required.
Change the password later under Settings → Security → Sign-in. A second factor and passkeys are added under Settings → Security → Sign-in; see Accounts, sessions and permissions.
Pair the desktop capture agent or the browser extension so links reach rDownloader automatically.
Optional. Pairing issues a capture token, shown exactly once. It lets a client push links into the LinkGrabber and read a narrow event stream — nothing else. A capture token cannot read download paths, change settings or reach the MCP endpoint.
Copy the token and hand it to whichever client you use:
rdownloader-capture configure --token <TOKEN>The browser extension takes the same token in its options page.
Pair the browser extension here if an account will need it. Hoster accounts that take over your browser's sign-in — DDownload, for example — can only receive that session through the extension. The step lists what to do (install the extension in the browser you are signed in to the hoster with, press Pair and copy the token, enter this server's address and the token in the extension options, Test connection, Save) and shows live whether an extension has reported in: Browser extension connected, or No browser extension has reported in yet. Without the extension, a username and password or an API key remain.
You can always add links by hand instead, and you can pair a client later under Settings → Clients & API — the Desktop tab for the capture agent, Browser for the extension.
See Desktop capture agent and Browser extension.
Downloads need a target directory. Add at least one storage root to continue.
This step is required. A storage root is the base directory downloads are written to. Paths must be absolute and are created if they do not exist yet.
Adding the first storage root also creates a default category named Downloads, so the queue has a destination even for a download that was never assigned a category.
In a container, only a path on a mounted volume survives the container being recreated. rDownloader marks a root that is not on a mounted volume rather than letting you discover it later.
More roots, per-root free-space thresholds, categories and routing rules are configured under Settings → Storage & rules — see Storage, categories and rules. Watched folders have a settings page of their own, Settings → Hotfolders.
Optionally create an API token for an external client or register the built-in MCP server with your AI assistant.
Optional. This creates an API token and shows the command that registers rDownloader with an MCP client:
claude mcp add --transport http rdownloader http://127.0.0.1:8710/mcp \
--header "Authorization: Bearer <TOKEN>"The token is shown once — if you lose it, revoke it and issue a new one. Skip this step unless you actually want an assistant driving the queue.
See MCP server.
Pick the services you use. Only their plugins are installed — everything else stays available in Settings → Plugins, one click away.
Hosters, multihosters, cloud drives, notification destinations and post-processing steps are plugins, and only the ones you use are installed. This step lists them by service, filtered by category — Hosters, Multihosters & debrid, Torrents & remote jobs, Cloud drives & storage, Link lists & folders, Metadata, Notifications, Post-processing — and searchable by name. A service is everything that belongs to it: ticking MEGA installs its downloads, its sign-in and its folders at once.
- Services that need no account are already installed on a fresh installation, so links work straight away. The step says so in an Already installed note above the list, and they stand ticked.
- A service marked Needs an account or destination does nothing until you add its account in the next step or its destination in the settings.
- An installed service can be unticked. Below the list the step counts what Continue will remove, next to what it will install. You can also leave everything ticked and switch a service off or remove it later under Settings → Plugins → Installed; when you run the wizard again from the settings, the note carries Open Settings → Plugins, which closes the wizard and opens that page.
Continue first removes what you unticked, then installs what you ticked. Removing asks once, Remove services?, naming each service: it goes with all of its plugins and stops running at the next start. Cancel there keeps you on the step with nothing changed. A service that an unfinished download still uses stays installed, and the step names it; the others are removed. A removed service is not installed again at a later start.
Installing shows a progress bar. Each plugin comes from the plugin repository when it offers the same or a newer version under the same key and asking for no more permissions, and from the bundle beside the program otherwise — without a network, for example (see Installing and trust). Then the accounts step opens and offers exactly what you chose; an account you add there can be tested straight away. If something you chose runs only after a restart, the accounts step says so; its accounts can still be added right away. Skip installs and removes nothing.
Everything you did not choose, and everything you removed, stays under Settings → Plugins → Catalogue, where one click installs it later; a release that adds a new plugin lists it there too, instead of installing it unasked. See Bundled plugins.
Add hoster accounts and Usenet servers. You can skip this and add them later in the settings.
Optional, and split into two tabs. If none of the services you chose takes an account, the step says so and offers Choose services to go back.
- Hoster accounts — premium hoster or multihoster credentials. They lift speed and captcha limits; without one, the bundled hosters still work through their anonymous flow. See Hosters and accounts. While no extension has reported in, the tab names the providers that can take over your browser's sign-in; an account waiting for the browser's session opens Pair the browser extension in a dialog, without leaving the assistant.
- Usenet — one or more NNTP servers. Without at least one, NZB downloads cannot run. See Usenet and NZB.
Credentials entered here go straight into the encrypted vault.
The last step offers Finish or Finish & take the tour. The tour is an eight-step walkthrough of the interface and can be replayed later; both it and this assistant are offered again from the System settings page.
The Status tab of the System settings page carries a readiness card that names what is still missing or misconfigured — an unmounted storage root, a missing external tool, an unpaired client. Read it once before you queue anything large.
Reasonable next steps:
- Add your first download.
- Set the interface language and theme under Settings → Interface → This browser, or from the gear in the sidebar footer.
- Decide which services you actually need — BitTorrent, Usenet, media, galleries, recordings and remote transfer can each be switched off under Settings → Services.
- If the service is reachable from outside this machine, read Security and privacy and Reverse proxy before exposing it.
- If you want widget captchas — reCAPTCHA, hCaptcha, Turnstile — answered by you rather than by a paid service, pair the browser extension. It is the only way a person answers one; see Hosters and accounts.
- If you want release pages recognised, look at Settings → Site rules. A fresh installation holds only the thirteen rules that come with rDownloader — Linux distributions, Blender, free software, Internet Archive items and paste services — switched off; import a rule export somebody gave you, or write a rule of your own. See Site rules.