Skip to main content

The documentation here is for an unreleased version of Recyclarr.

Visit the documentation site for the Current Version instead.

Client and Server

Recyclarr has two programs:

  • The server (recyclarr-server) does the work. It reads your configuration, talks to Sonarr and Radarr, runs syncs, and sends notifications.
  • The CLI (recyclarr) is a client. Each command sends a request to a server and shows the result. Other programs can send the same requests through the HTTP API.

The server reads your YAML configuration and settings.yml when it starts. If either is not valid, the server does not start. A persistent server applies later edits to your YAML configuration on its own, but needs a restart for changes to settings.yml. See Configuration Changes.

Persistent Server​

A persistent server keeps running until you stop it. The Docker image and the Helm chart run one, and recyclarr serve starts one on your own machine.

A persistent server:

A persistent server needs an API key and does not start without one.

For CLI commands to use a persistent server, set server.base_url in cli.yml or set the RECYCLARR_SERVER_URL environment variable. The Docker image sets the variable for you.

Temporary Server​

If no server address is set, each CLI command starts its own temporary server. The temporary server listens only on the local machine, handles that one command, and stops when the command ends. It does not run the built-in schedule, opens no management port, and does not keep its jobs after it stops. It writes log files to logs/server/ in the data directory and sends notifications. It downloads guide data only when its cached copy is out of date, so most commands start without network access.

This is the default when you run recyclarr outside Docker without any extra setup. You do not need to set an API key: the CLI creates a new one-time key for each command and gives it to the temporary server.

Configuration Changes​

A persistent server applies edits to your YAML configuration while it runs, without a restart. Once a minute, when it checks for guide data updates, it compares the contents of these files with the previous check:

  • YAML files in the configs directory
  • recyclarr.yml or recyclarr.yaml
  • secrets.yml or secrets.yaml
  • Local files you add with config includes, whether in the includes directory or at an absolute path
  • Files you read with the !file tag

Creating, deleting, or editing any of these files counts as a change. When the server finds one, it loads the configuration again:

  • If the new configuration is valid, the server logs Configuration changed and was reloaded, and the next sync uses it. A sync that is already running finishes with the configuration it started with.
  • If the new configuration is not valid, the server logs its errors once, followed by Configuration changed but is invalid. It keeps syncing with the previous configuration and does not try again until you change the files again. Until then, the errors stay in the server diagnostics.
  • If a sync or another request that reads guide data is running during a check, the server leaves your edit for the next check where none is running.

Changes to settings.yml and to environment variables need a restart. An invalid configuration still stops the server when it starts.

A temporary server reads your configuration fresh for each command, so edits always apply to the next command.

Server Diagnostics​

Server diagnostics are problems the server has right now that you need to fix, such as a deprecated setting or a configuration edit it could not use. The server logs each problem when it finds it, and also keeps it in a list until the problem is gone. You see this list in three places:

  • Notifications: Every sync notification has a Server section with the current diagnostics. While the list is not empty, the server sends a notification after every sync, even when the sync itself had nothing to report.
  • recyclarr sync: The sync command lists them under Sync Diagnostics after the results, and in the log output when you use --log. They do not change the exit code. If the server cannot return the list, the command shows its results without it.
  • HTTP API: GET /api/v1/diagnostics returns the list.
CodeSeverityCauseGoes away when
environmentVariableRemovedwarningA Recyclarr 8 Docker variable such as CRON_SCHEDULE is still setYou remove the variable and restart the server
settingDeprecatedwarningsettings.yml uses a deprecated settingYou remove the setting and restart the server
configPropertyDeprecatedwarningA configuration file uses a deprecated propertyThe server loads your configuration without it
configEditRejectederrorAn edit to your configuration is not valid, so the server syncs with the previous configurationThe server loads a valid edit, or you change the files back
guideUpdateRejectedwarningNew guide data made your configuration invalid, so the server went back to the last data that workedA later guide data update leaves your configuration valid
resourceProviderUpdateFailedwarningA resource provider could not be downloaded, so syncs use its cached copyThe next download of that provider succeeds

The server reads settings.yml and environment variables only when it starts, so those problems last until a restart. It checks your configuration each time it loads it, such as at startup and after you edit it.

The API returns errors first. Each diagnostic has an id that stays the same while the problem lasts, a code from the table above, a severity, a message, and a data object. The API reference lists the data fields for each code. Reading the list changes nothing, and the list is empty when the server has no problems:

{
"diagnostics": [
{
"id": "environmentVariableRemoved:CRON_SCHEDULE",
"code": "environmentVariableRemoved",
"severity": "warning",
"message": "CRON_SCHEDULE is no longer used; set `server.schedule.cron` in settings.yml instead. See https://recyclarr.dev/guide/upgrade-guide/v9.0/#cron-schedule",
"data": { "variable": "CRON_SCHEDULE" }
}
]
}

The server keeps the list in memory and builds it again after a restart. Problems found at startup appear right away. A guide data update that was held back appears again the next time the server updates that provider, up to one hour after the restart.

Server API Key​

Every request to the server's API (any path under /api) must include the server API key. This keeps other programs on your network, or other users on your machine, from starting syncs or deleting custom formats in your Sonarr and Radarr instances. The API reference pages need no key. Health probes and metrics need no key either, but they are on the separate management port, not the API port.

Setting the Key​

The server reads its key from one of two environment variables, never from settings.yml:

Set only one of them. The server logs a fatal error and exits with a non-zero exit code when neither is set, when both are set, when it cannot read the key file, or when the key is shorter than 32 characters. This applies to recyclarr serve, the Docker image, and any other way you run a persistent server.

Use a long random value, for example:

openssl rand -hex 32

The server reads the key file again on every request, so you can rotate the key by replacing the file's contents without a restart. If the file later becomes unreadable or holds a key that is too short, the server rejects every request and logs the cause.

Sending the Key​

  • The CLI sends the key from server.api_key in cli.yml, or from RECYCLARR_API_KEY or RECYCLARR_API_KEY_FILE when either is set. Inside the Docker container, the CLI reads the same variables as the server, so docker exec commands need no extra setup.

  • Other HTTP clients send the key as a bearer token in the Authorization header:

    curl -H "Authorization: Bearer $RECYCLARR_API_KEY" http://localhost:7982/api/v1/sync/jobs

When the key is missing or wrong, the server responds with 401 Unauthorized, a WWW-Authenticate: Bearer header, and a Problem Details body. The CLI shows this message:

The Recyclarr server rejected the request: missing or wrong API key. Set server.api_key in cli.yml, or the RECYCLARR_API_KEY or RECYCLARR_API_KEY_FILE environment variable, to the key the server uses.

Network Security​

The server serves plain HTTP and has no TLS settings. The API key travels unencrypted between a client and the server, and the management port needs no key at all. Decide which clients can reach each port, and add TLS where traffic crosses a network you do not trust.

  • TLS: Terminate TLS in front of the server with a reverse proxy, a tunnel, a Kubernetes Ingress, or a service mesh. Plain HTTP between that proxy and the server is fine on a network you trust.
  • API port: Publish it only to the clients that need it. CLI commands run with docker exec reach the server inside the container, so they need no published port at all.
  • Management port: It listens on the same address as the API port. In Docker, publish it only if something outside the container scrapes metrics or probes health. In Kubernetes, probes and Prometheus reach it on the pod IP, so restrict it with a NetworkPolicy.

To publish the API port only on the Docker host itself, bind it to the loopback address:

services:
recyclarr:
ports:
- 127.0.0.1:7982:7982

This NetworkPolicy lets only pods in a monitoring namespace reach the management port, while the API port stays open to the rest of the cluster. Health probes still work, because a NetworkPolicy always allows traffic from the pod's own node, where the kubelet runs. Adjust the selectors to your cluster:

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: recyclarr
spec:
podSelector:
matchLabels:
app.kubernetes.io/name: recyclarr
policyTypes:
- Ingress
ingress:
- ports:
- port: 7982
- from:
- namespaceSelector:
matchLabels:
kubernetes.io/metadata.name: monitoring
ports:
- port: 7983

API Reference​

Each server describes its own API on the same address and port as the API itself, so the description always matches the version you run:

  • /scalar is an interactive reference page where you can browse operations and try requests.
  • /openapi/v1.json is the OpenAPI document, for tools that generate clients or import an API.

Both paths are open without the API key. Requests you send from the /scalar page go to /api, so enter the key there before you try them. This site also has the reference under HTTP API.

Sync Jobs​

Every sync runs as a job, whether the schedule, the CLI, or the API started it. The server runs one job at a time, oldest first. Other jobs wait in a queue. A job that runs longer than the sync time limit stops so that the next job can start.

Each job has one of these statuses:

StatusMeaning
pendingWaiting in the queue
runningSyncing now
succeededThe sync finished without errors
partialThe sync finished, but some changes failed
failedThe sync failed
interruptedThe server stopped while the job was pending or running
skippedA scheduled sync was not started because another job was already active

A persistent server keeps the 50 most recent finished jobs and their results, including across restarts. When the server starts, it marks jobs that were active at shutdown as interrupted. It does not run them again.