macOS (Homebrew)

This guide runs the Recyclarr server as a Homebrew service on macOS. The service starts when you log in and starts again if the server fails. The server then syncs on its built-in schedule and accepts commands from the CLI.

Before you start, install Recyclarr with Homebrew.

Add Your Configuration

The service runs as your user and uses your normal configuration directory, ~/Library/Application Support/recyclarr. Put your YAML configuration there, for example in recyclarr.yml. See Getting Started for what to put in the file, and File Structure for the configs and includes subdirectories.

Set the API Key

The server does not start without an API key. Homebrew gives the service the variables in an environment file named recyclarr.env. The file is in ~/.homebrew/services/, or in $XDG_CONFIG_HOME/homebrew/services/ if you set XDG_CONFIG_HOME. These commands create it with a random key in the right place:

env_dir="${XDG_CONFIG_HOME:+$XDG_CONFIG_HOME/homebrew}"
env_dir="${env_dir:-$HOME/.homebrew}/services"
mkdir -p "$env_dir"
echo "RECYCLARR_API_KEY=$(openssl rand -hex 32)" > "$env_dir/recyclarr.env"
chmod 600 "$env_dir/recyclarr.env"

Homebrew ignores the file if other users can write to it. The file stays in place when you upgrade Recyclarr.

To use a different configuration directory, add an absolute RECYCLARR_CONFIG_DIR line to the same file.

Start the Service

brew services start recyclarr

brew services list shows started while the server runs. If the configuration or API key is not valid, it shows error, and the server tries again about every 10 seconds until you fix the problem or stop the service.

To stop the service and keep it from starting at login:

brew services stop recyclarr

Logs

The server writes log files to logs/server/ in the configuration directory. Homebrew also saves the server's error output to $(brew --prefix)/var/log/recyclarr.log. If the service does not start and the log files show no cause, look there.

Run CLI Commands

The CLI sends commands to the server over HTTP. To use the service, give the CLI the server address and the API key in cli.yml in your configuration directory (see CLI settings):

server:
  base_url: http://localhost:7982
  api_key: your-key-here

Use the key from recyclarr.env. Then run commands as usual:

recyclarr sync

Without cli.yml, each command starts its own temporary server and does not use the service. The server listens on port 7982 on the local machine only. To change this, see the server settings.

Configuration Changes

The server reads your YAML configuration and settings.yml once, when it starts. After you change them or recyclarr.env, restart the service:

brew services restart recyclarr

Upgrade

brew upgrade does not restart the service; the old version keeps running until you restart it:

brew update
brew upgrade recyclarr
brew services restart recyclarr