# autobrr

> The modern autodl-irssi replacement.

This file contains all documentation content in a single document following the llmstxt.org standard.

## Cross-seed with autobrr

:::tip[Using qBittorrent?]
If you run qBittorrent, check out [qui](https://getqui.com), our multi-instance qBittorrent WebUI with first party cross-seed support. It integrates directly with autobrr and needs no extra daemon or config; see [Cross-seed with qui](../filters/cross-seed-qui.mdx).
:::

:::info[Heads up]

This is meant for advanced users. If you're not familiar with cross-seed already, we suggest you read their [documentation](https://cross-seed.org) before you continue.

Don't expect any support for setting this up. If you need help setting up cross-seed, you need to reach out to them directly.

:::

With this setup you can use autobrr with [cross-seed](https://github.com/cross-seed/cross-seed) to automatically cross-seed newly announced torrents from indexer Y that matches existing torrents in your torrent client from indexer X.

### Install cross-seed {/* #cross-seed-install */}

See [cross-seed's documentation](https://www.cross-seed.org/docs/basics/getting-started) on how to get started.

### Create the cross-seed filter in autobrr {/* #cross-seed-filter */}

The way this works is you create a filter with a higher priority set than any other filter to make sure every cross-seed match is forwarded to the cross-seed daemon instead of being run through other filters.

1. Get your API key with the following command:

    ```
    cross-seed api-key
    ```
    Keep this key at hand since we will need it at step 5 later on.
    In the rest of this tutorial, we will refer to this as `YOUR_API_KEY`.

2. Create a filter and name it eg. `cross-seed`.
3. Select all the indexers you want to use, preferably all of them.
4. Set a really high `priority` to make sure it's always higher than your other filters.
5. Go to the `External` tab, and add a new External filter.

   - Type: `Webhook`
   - Host: `http://localhost:2468/api/announce`
   - Headers: `x-api-key=YOUR_API_KEY`
   - HTTP Method: `POST`
   - Expected http status: `200`
   - Data (JSON):

   ```json
   {
     "name": {{ toRawJson .TorrentName }},
     "guid": "{{ .TorrentUrl }}",
     "link": "{{ .TorrentUrl }}",
     "tracker": {{ toRawJson .IndexerName }}
   }
   ```

6. Go to the `Actions` tab and create a Test action. This is required for the webhook to work.
7. Finally, make sure the filter is enabled and you're all set.

:::tip[Cross-seed notifications]
You can set up a Notifiarr or Apprise webhook for cross-seed notifications within the cross-seed config.
:::

---

## Manage torrents

You have probably reached a point now where you want to start automatically manage torrents in your preferred client based on rules, like min seed time and max ratio.

We'll cover the most popular ones. Some of these tools only support a single client and others support multiple.

## autoremove-torrents

> This program is a tool that can help you remove torrents automatically. Now, you don’t need to worry about your disk space anymore - according to your strategies, the program will check each torrent if it satisfies the remove condition; If so, delete it automatically.

Documentation: [autoremove-torrents](https://autoremove-torrents.readthedocs.io/en/latest/)

Repository: [jerrymakesjelly/autoremove-torrents](https://github.com/jerrymakesjelly/autoremove-torrents)

Supported clients
* qBittorrent
* Transmission
* μTorrent
* Deluge
* rTorrent (planned)

autoremove-torrents uses `task` and `strategy` with properties to define what you want to do. 

To run your configuration periodically we recommend a cronjob on Linux/Mac or the Task Scheduler on Windows.

Example config:

```yaml
# A task block
my_task:          # Part 1: Task Name
  # Part 2: Login Information
  client: qbittorrent
  host: http://127.0.0.1:9091
  username: admin
  password: adminadmin
  # Part 3: Strategies Block (Remove Conditions)
  strategies:
    strategy1:    # Part I: Strategy Name
      # Part II: Filters
      categories:
        - IPT
      # Part III: Remove Condition
      ratio: 1
      seeding_time: 1209600
    strategy2:
      all_categories: true
      excluded_categories:
        - tv
        - movies
      seeding_time: 259200
    # Add more strategies here...
  # Part 4: Decide whether to remove and delete data (optional)
  delete_data: true
```

## tqm

> CLI application to manage torrent client queues and remove torrents that meet a specific criteria 

Repository (original, not active): [https://github.com/l3uddz/tqm](https://github.com/l3uddz/tqm)  
Repository (fork, active): [https://github.com/autobrr/tqm](https://github.com/autobrr/tqm)

The [original](https://github.com/l3uddz/tqm) only supports `categories` in qBittorrent but the [fork](https://github.com/autobrr/tqm) supports rules by `tags` as well.

Supported clients
* qBittorrent
* Deluge

TQM has powerful rules with conditionals which makes it a bit harder to setup but you have fine-grained control.  
It supports `remove`, `tagging` and `update categories`.  

To run your configuration periodically we recommend a cronjob on Linux/Mac or the Task Scheduler on Windows.

Example config (fork with tags support):

```yaml
clients:
  qbt:
    download_path: /mnt/local/downloads/torrents/qbittorrent/completed
    download_path_mapping:
      /downloads/torrents/qbittorrent/completed: /mnt/local/downloads/torrents/qbittorrent/completed
    enabled: true
    filter: default
    type: qbittorrent
    url: https://qbittorrent.domain.com/
    user: user
    password: password
filters:
  default:
    ignore:
      # general
      - TrackerStatus contains "Tracker is down"
      - Downloaded == false && !IsUnregistered()
      - SeedingHours < 26 && !IsUnregistered()
      # permaseed / un-sorted (unless torrent has been deleted)
      - Label startsWith "permaseed-" && !IsUnregistered()
      # Filter based on qbittorrent tags (only qbit at the moment)
      - '"permaseed" in Tags && !IsUnregistered()'
    remove:
      # general
      - IsUnregistered()
      # imported
      - Label in ["sonarr-imported", "radarr-imported", "lidarr-imported"] && (Ratio > 4.0 || SeedingDays >= 15.0)
      # ipt
      - Label in ["autoremove-ipt"] && (Ratio > 3.0 || SeedingDays >= 15.0)
      # hdt
      - Label in ["autoremove-hdt"] && (Ratio > 3.0 || SeedingDays >= 15.0)
      # bhd
      - Label in ["autoremove-bhd"] && (Ratio > 3.0 || SeedingDays >= 15.0)
      # ptp
      - Label in ["autoremove-ptp"] && (Ratio > 3.0 || SeedingDays >= 15.0)
      # btn
      - Label in ["autoremove-btn"] && (Ratio > 3.0 || SeedingDays >= 15.0)
      # hdb
      - Label in ["autoremove-hdb"] && (Ratio > 3.0 || SeedingDays >= 15.0)
      # Qbit tag utilities
      - HasAllTags("480p", "bad-encode") # match if all tags are present
      - HasAnyTag("remove-me", "gross") # match if at least 1 tag is present
    label:
      # btn 1080p season packs to permaseed (all must evaluate to true)
      - name: permaseed-btn
        update:
          - Label == "sonarr-imported"
          - TrackerName == "landof.tv"
          - Name contains "1080p"
          - len(Files) >= 3

      # cleanup btn season packs to autoremove-btn (all must evaluate to true)
      - name: autoremove-btn
        update:
          - Label == "sonarr-imported"
          - TrackerName == "landof.tv"
          - not (Name contains "1080p")
          - len(Files) >= 3
    # Change qbit tags based on filters
    tag:
      - name: low-seed
      # This must be set
      # "mode: full" means tag will be added to
      # torrent if matched and removed from torrent if not
      # use `add` or `remove` to only add/remove respectivly
      # NOTE: Mode does not change the way torrents are flagged,
      # meaning, even with "mode: remove",
      # tags will be removed if the torrent does NOT match the conditions.
      # "mode: remove" simply means that tags will not be added
      # to torrents that do match.
        mode: full
        update:
          - Seeds <= 3
```

::::info
There are more operators (i.e. `==` `!=` `||` and `&&`) you can use than those provided in the example config.  
To see a full list of available operators head over to the Language Definition documentation of Expr -  
the language used to filter within TQM:  
[Expr Lang v1.9 - Language Definition: Supported Operators](https://expr-lang.org/docs/v1.9/language-definition#supported-operators)
::::

## qbittools

> qbittools is a feature rich CLI for the management of torrents in qBittorrent.

Repository: [https://gitlab.com/AlexKM/qbittools](https://gitlab.com/AlexKM/qbittools)

Supported clients
* qBittorrent

Commands:
- `add` (add torrents via cli)
- `unpause`
- `tagging` (unregistered, not working etc)
- `reannounce` (continiously look for torrents to re-announce, can be very useful)
- `update passkey` (in case you need to update your passkey this makes it easy to do in bulk)
- `export` (export torrents by category or tags)
- `mover` (change category: useful for hybrid setups with nvme/hdd)
- `orphaned` (find files not assosciated with any torrent)

To run the commands periodically (that do not run in daemon mode natively) we recommend a cronjob on Linux/Mac or the Task Scheduler on Windows.

## qbit_manage

> This tool will help manage tedious tasks in qBittorrent and automate them. Tag, categorize, remove Orphaned data, remove unregistered torrents and much much more. 

Documentation: [https://github.com/StuffAnThings/qbit_manage/wiki](https://github.com/StuffAnThings/qbit_manage/wiki)

Repository: [https://github.com/StuffAnThings/qbit_manage](https://github.com/StuffAnThings/qbit_manage)

Supported clients
* qBittorrent

`qbit_manage` has a lot of features: 
- `remove`
- `tagging`
- `changing categories`
- integrates well with arrs to check hardlinks
- `notifications` (apprise, notifiarr, webhooks)

To run your configuration periodically we recommend a cronjob on Linux/Mac or the Task Scheduler on Windows.

---

## seasonpackarr

seasonpackarr is a companion app for autobrr that automagically hardlinks downloaded episodes into a season folder when a season pack is announced, eliminating the need for re-downloading existing episodes.

For a detailed setup and configuration guide you can follow the instructions available at [https://github.com/nuxencs/seasonpackarr](https://github.com/nuxencs/seasonpackarr/blob/develop/README.md). If you still have issues or questions, feel free to open up an issue on GitHub or join the [TRaSH Discord](https://trash-guides.info/discord) server and ask your questions in the seasonpackarr channel!

---

## Sizechecker

**Sizechecker** is a companion tool for **autobrr** that helps prevent accepting new downloads when certain disk space conditions are met. It can check both used and available disk space and can send notifications to a Discord webhook if the specified threshold is crossed.

## Step 1: Grab the Binary

1. Open your terminal.

2. Run the following command to download the appropriate binary for your Linux system:

For **Linux (AMD64)**:

```bash
wget $(curl -s https://api.github.com/repos/s0up4200/sizechecker/releases/latest | grep download | grep linux_amd64 | cut -d\" -f4)
```

For **Linux (ARM64)**:

```bash
wget $(curl -s https://api.github.com/repos/s0up4200/sizechecker/releases/latest | grep download | grep linux_arm64 | cut -d\" -f4)
```

3. Extract the downloaded tar.gz file:

```bash
tar -xzf sizechecker_1.0.0*.tar.gz
```

4. Once extracted, make the binary executable:

```bash
chmod +x sizechecker
```

5. (Optional) Move the binary to a directory in your `PATH` to make it globally accessible:

```bash
sudo mv sizechecker /usr/local/bin/
```

### Step 2: Usage Examples

#### 1. Check Available Disk Space and Notify via Discord Webhook

The basic usage of the tool is to check the available disk space on a specified directory and optionally send a Discord notification if the available space is below a certain threshold.

**Example:**

```bash
sizechecker --limit=50GB --runtype=a --discord="YOUR_DISCORD_WEBHOOK_URL" /path/to/check
```

- `--limit=50GB`: This sets the **minimum required free space** in the specified directory.
- `--runtype=a`: This tells the tool to check for **available** disk space.
- `--discord`: This is the Discord webhook URL where the notification will be sent if the disk space is below the specified limit.
- `/path/to/check`: This is the directory where you want to check available space. E.g., `~/` for your home directory.

#### 2. Check Used Disk Space and Notify via Discord Webhook

You can also use the tool to check the used disk space in a specified directory, and send a notification if the used space exceeds a certain limit.

**Example:**

```bash
sizechecker --limit=500GB --runtype=u --discord="YOUR_DISCORD_WEBHOOK_URL" /path/to/check
```

- `--limit=500GB`: This sets the **maximum allowed used space** in the specified directory.
- `--runtype=u`: This tells the tool to check for **used** disk space.
- `--discord`: Discord webhook URL for notifications.
- `/path/to/check`: The directory to check.

#### 3. Set a Cooldown to Avoid Frequent Notifications

You can specify a cooldown period between notifications to prevent the tool from sending too many messages to Discord in a short time. By default, the cooldown is set to 1 minute if not specified.

**Example:**

```bash
sizechecker --discord="YOUR_DISCORD_WEBHOOK_URL" --cooldown=5m --limit=50GB --runtype=a /path/to/check
```

- `--cooldown=5m`: This sets a cooldown period of 5 minutes between notifications. If the disk space check fails within the cooldown period, no additional notification will be sent.

### Step 3: Setup in autobrr

1. Inside an **autobrr filter**, go to the **External** tab.

2. Click **Add New**.

3. Choose **Type: Exec**.

4. **Name**: Give it a name like `sizechecker`.

5. **Path**: To find the full path of the `sizechecker` binary, you can use the following command:

   ```bash
   which sizechecker
   ```

   Copy the output and paste it into the **Path** field.

6. **Exec Arguments**: Add the required arguments. For example, to check for at least 50GB free space in `/path/to/check`, add the following:

   ```bash
   --discord="YOUR_DISCORD_WEBHOOK_URL" --limit=50GB --runtype=a /path/to/check
   ```

7. **Expected Exit Status**: Set the expected exit status to `0`.

![autobrr-sizechecker-setup](../../static/img/sizechecker.png)

**Additional Information:**

- The `--runtype` flag accepts two values:
  - `a`: Check for **available** free space. The tool will warn if the available space is **less than** the specified limit.
  - `u`: Check for **used** disk space. The tool will warn if the used space is **greater than** the specified limit.

- The `--limit` flag works differently based on the `--runtype`:
  - For `runtype=a`, `--limit` specifies the **minimum required free space**.
  - For `runtype=u`, `--limit` specifies the **maximum allowed used space**.

---

## Upgraderr

## Arr, deduplication, and cross-seed functionality {/* #upgraderr */}

:::info[Heads up]
This is meant for any kind of user. There is no configuration, and it's nearly impossible to make a mistake so long as the guide is followed with the modest amount of care.
:::

### What is this {/* #what-is-upgraderr */}

Upgraderr is a title parser that matches existing titles present in your qBittorrent client with the title submitted and returns a HTTP return code. The return codes indicate an action to perform next, if applicable.

### Arr functionality {/* #upgraderr-arr-functionality */}

On any filter, you may utilize the external tab as a pre-filter. Using this with a return code of 200 permits any unique titles to be added, or if they're a quality upgrade. This also acts as a deduplicator should you wish.

Coupling this with the extensive filtering built into autobrr, you can define the quality above which you no longer want to accept upgrades, if you wish. This allows you to replace applications such as Sonarr / Radarr.

On the external Webhook action, utilize the following payload, replacing the host(s), user and password with your configuration. The expected return code is 200.

- Host:

```
http://upgraderr:6940/api/upgrade
```

- Payload:

```json
{
  "host": "http://qbittorrent:8080",
  "user": "username",
  "password": "password",
  "name": {{ toRawJson .TorrentName }}
}
```

### Cross-Seed functionality {/* #upgraderr-cross-seed-functionality */}

At the time of this writing, Upgraderr has excellent cross-seed functionality that runs in milliseconds.
Currently, a partial matching system is in place where if 80% of the data matches an existing torrent, any conflicting files in the new torrent (if they exist) will be renamed to avoid corrupting the original torrent.

On the external Webhook action, utilize the following payload, replacing the host(s), user and password with your configuration. The expected return code is 250.

- Host:

```
http://upgraderr:6940/api/upgrade
```

- Payload:

```json
{
  "host": "http://qbittorrent:8080",
  "user": "username",
  "password": "password",
  "name": {{ toRawJson .TorrentName }}
}
```

Once the pre-hook succeeds, create a Webhook action, replacing the same variables as before.

- Host:

```
http://upgraderr:6940/api/cross
```

- Payload:

```json
{
  "host": "http://qbittorrent:8080",
  "user": "username",
  "password": "password",
  "name": {{ toRawJson .TorrentName }},
  "hash": "{{ .TorrentHash }}",
  "torrent": "{{ .TorrentDataRawBytes | js }}"
}
```

### Finally {/* #upgraderr-final-words */}

This is a toolchest, other functionality can be achieved by using other return codes, and attaching other tools to actions taken by the application.

More Information: [github.com/kylesanderson/upgraderr](https://github.com/kylesanderson/upgraderr)

---

## API Docs

# autobrr API

autobrr is a powerful automation tool. With the help of our API, users and developers can integrate and extend the functionalities of autobrr into their own applications, tools, or systems.

## API Endpoint Reference

The **API Endpoint Reference** provides a comprehensive list of available endpoints for interacting with our API.

**Base URL:** `http://127.0.0.1:7474/api`

### Available Endpoints

| #   | Endpoint Description         | Endpoint Path                       |
| --- | ---------------------------- | ----------------------------------- |
| 1   | Liveness Check               | `/healthz/liveness`                 |
| 2   | Readiness Check              | `/healthz/readiness`                |
| 3   | Download Clients             | `/download_clients`                 |
| 4   | Feeds                        | `/feeds`                            |
| 5   | Specific Feed Status         | `/feeds/<FEED_ID>/enabled`          |
| 6   | Filters                      | `/filters/`                         |
| 7   | Specific Filter Status       | `/filters/<FILTER_ID>/enabled`      |
| 8   | Indexer                      | `/indexer`                          |
| 9   | Specific Indexer Status      | `/indexer/<INDEXER_ID>/enabled`     |
| 10  | IRC Networks                 | `/irc`                              |
| 11  | Restart Specific IRC Network | `/irc/network/<NETWORK_ID>/restart` |
| 12  | API Keys                     | `/keys`                             |
| 13  | Notifications                | `/notification`                     |
| 14  | Release History              | `/release`                          |
| 15  | Release Cleanup Jobs         | `/release/cleanup-jobs`             |
| 16  | Config                       | `/config`                           |
| 17  | Actions                      | `/actions`                          |
| 18  | Lists                        | `/lists`                            |
| 19  | Proxies                      | `/proxy`                            |
| 20  | Updates                      | `/updates`                          |
| 21  | Logs                         | `/logs`                             |
| 22  | List Refresh Webhooks        | `/webhook/lists/trigger`            |

### Authentication

All API requests except the [health check endpoints](#health-check-endpoints) require an API key for authentication. This key can be generated from your autobrr dashboard by going to `Settings` -> `API keys`. Remember to always keep your API key confidential.

![API dashboard](/img/api-dashboard.png)

#### Sending the API Key

When making requests to the autobrr API, you can provide your API key in two ways:

- **Header (Recommended)**: Include the API key in the request header using `X-API-Token`. This method is more secure as it avoids exposing the key in the URL.
- **URL Parameter:** Directly append the API key to the endpoint URL as a query parameter. This method is straightforward but might expose the key in logs or browser history.

**Using the API key in the header:**

```bash
curl -X GET 'http://127.0.0.1:7474/api/download_clients' -H 'X-API-Token: AUTOBRR_API_KEY' | jq
```

**Using the API key as an URL parameter:**

```bash
curl -X GET 'http://127.0.0.1:7474/api/download_clients?apikey=${AUTOBRR_API_KEY}' | jq
```

## Health Check Endpoints

autobrr provides two health check endpoints to monitor the state and readiness of the application.

These endpoints do **not** require an API key, so they can be used directly in a Docker `HEALTHCHECK` or Kubernetes probe without embedding credentials.

### Liveness Check

This endpoint checks if the autobrr application is running.

```bash
curl -X GET 'http://127.0.0.1:7474/api/healthz/liveness'
```

**Response:**

**200 OK:** The application is alive and running.

### Readiness Check

This endpoint checks if the application and its dependencies (e.g., database) are not only running but also ready to accept requests.

```bash
curl -X GET 'http://127.0.0.1:7474/api/healthz/readiness'
```

**Responses:**

- **200 OK:** The application and its dependencies are ready to accept requests.
- **500 Internal Server Error:** There's an issue with one or more dependencies.
  - **Unhealthy. Database unreachable:** Indicates that there's an issue connecting to the Postgres database. Note that SQLite, if used, doesn't typically present availability issues, so this error is more relevant when using Postgres.

## Filters

### Fetch all filters

Retrieve a list of all filters available on your autobrr instance.

```bash
curl -X GET 'http://127.0.0.1:7474/api/filters' -H 'X-API-Token: AUTOBRR_API_KEY' | jq '.[] | {id, name}'
```

### Enable or disable a filter

Toggle the status of a specific filter.

```bash
curl -X PUT 'http://127.0.0.1:7474/api/filters/65/enabled' -H 'X-API-Token: AUTOBRR_API_KEY' \
     -d '{"enabled":true}'
```

### Delete a filter

Remove a specific filter from your autobrr instance.

```bash
curl -X DELETE 'http://127.0.0.1:7474/api/filters/84' -H 'X-API-Token: AUTOBRR_API_KEY'
```

### Create a filter

Create a new filter.

```bash
curl -X POST 'http://127.0.0.1:7474/api/filters' -H 'X-API-Token: AUTOBRR_API_KEY' \
-d '{
    "name": "filter name",
    "enabled": false,
    "resolutions": [],
    "codecs": [],
    "sources": [],
    "containers": [],
    "origins": []
}'
```

### Update an existing filter

```bash
curl -X PATCH 'http://127.0.0.1:7474/api/filters/80' -H 'X-API-Token: AUTOBRR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
    "enabled": true,
    "priority": 1,
    "use_regex": false,
    "years": "2023-2030",
    "resolutions": [],
    "sources": [],
    "codecs": [],
    "containers": [],
    "match_hdr": [],
    "except_hdr": [],
    "match_other": [],
    "except_other": [],
    "smart_episode": false,
    "except_releases": "*24bit?Lossless*",
    "tags": "electronic,deep.house,progressive.house,house,techno,melodic.house,trance,breakbeat,mainstage,dance,progressive.trance,vocal.trance",
    "except_tags": "japanese",
    "match_language": [],
    "except_language": [],
    "formats": [
        "FLAC"
    ],
    "quality": [
        "Lossless"
    ],
    "media": [],
    "match_release_types": [],
    "origins": [],
    "except_origins": [],
    "indexers": [
        {
            "id": 21,
            "name": "Redacted",
            "identifier": "redacted"
        }
    ],
    "actions": [
        {
            "name": "Anjunabeats/Anjunadeep",
            "type": "QBITTORRENT",
            "enabled": true,
            "category": "red_labels",
            "tags": "Anjuna",
            "reannounce_interval": 7,
            "reannounce_max_attempts": 25,
            "client_id": 16,
            "webhook_method": "",
            "webhook_type": ""
        }
    ],
    "external": [
        {
            "id": 4,
            "name": "webhook",
            "index": 0,
            "type": "WEBHOOK",
            "enabled": true,
            "webhook_host": "http://service:42135/hook",
            "webhook_method": "POST",
            "webhook_data": "{\n    \"torrent_id\": {{.TorrentID}},\n    \"apikey\": \"redacted.apikey\",\n    \"maxsize\": 2147483648,\n    \"record_labels\": \"Label1,Label2\"\n}",
            "webhook_expect_status": 200
        }
    ]
}'
```

## Indexers

### Fetch all indexers

Retrieve a list of all indexers configured in your autobrr instance.

```bash
curl -X GET 'http://127.0.0.1:7474/api/indexer' -H 'X-API-Token: AUTOBRR_API_KEY' | jq '.[] | {id, name, enabled}'
```

### Enable or disable an indexer

Toggle the status of a specific indexer.

```bash
curl -X PATCH 'http://127.0.0.1:7474/api/indexer/31/enabled' -H 'X-API-Token: AUTOBRR_API_KEY' \
     -d '{"enabled": true}'
```

## IRC Networks

### List all networks

```bash
curl -X GET 'http://127.0.0.1:7474/api/irc' -H 'X-API-Token: AUTOBRR_API_KEY' | jq '.[] | {id, name, healthy}'
```

### Restart a network

```bash
curl -X GET 'http://127.0.0.1:7474/api/irc/network/5/restart' -H 'X-API-Token: AUTOBRR_API_KEY'
```

### Manually process an announce

Push a raw announce line through a channel's announce processor, as if it had just arrived on IRC. Give the channel name without the `#` prefix. Useful for testing filters against a real announce line.

```bash
curl -X POST 'http://127.0.0.1:7474/api/irc/network/5/channel/announce-channel/announce/process' -H 'X-API-Token: AUTOBRR_API_KEY' \
-d '{"msg": "New Torrent Announcement: <Movies> Name:Some.Movie.2026.1080p.BluRay.x264-GROUP ..."}'
```

## Feeds

### Fetch all feeds

Retrieve a list of all feeds available on your autobrr instance.

```bash
curl -X GET 'http://127.0.0.1:7474/api/feeds' -H 'X-API-Token: AUTOBRR_API_KEY' | jq '.[] | {id, name, enabled}'
```

### Enable or disable a feed

Toggle the status of a specific feed.

```bash
curl -X PATCH 'http://127.0.0.1:7474/api/feeds/8/enabled' -H 'X-API-Token: AUTOBRR_API_KEY' \
     -d '{"enabled": true}'
```

### Clear the cache of a feed

```bash
curl -X DELETE 'http://127.0.0.1:7474/api/feeds/8/cache' -H 'X-API-Token: AUTOBRR_API_KEY'
```

## Download clients

### List all download clients

```bash
curl -X GET 'http://127.0.0.1:7474/api/download_clients' -H 'X-API-Token: AUTOBRR_API_KEY' | jq
```

### Add a new download client

```bash title="qBittorrent"
curl -X POST 'http://127.0.0.1:7474/api/download_clients' -H 'X-API-Token: AUTOBRR_API_KEY' \
-d '{
  "name": "qbit",
  "type": "QBITTORRENT",
  "enabled": true,
  "host": "http://172.17.0.1:10963",
  "port": 0,
  "tls": false,
  "tls_skip_verify": false,
  "username": "username",
  "password": "password",
  "settings": {
    "basic": {
      "auth": true,
      "username": "username",
      "password": "password"
    },
    "rules": {
      "enabled": true,
      "max_active_downloads": 1,
      "ignore_slow_torrents": true,
      "ignore_slow_torrents_condition": "MAX_DOWNLOADS_REACHED",
      "download_speed_threshold": 10000,
      "upload_speed_threshold": 400
    }
  }
}'
```

```bash title="Deluge"
curl -X POST 'http://127.0.0.1:7474/api/download_clients' -H 'X-API-Token: AUTOBRR_API_KEY' \
-d '{
  "name": "Deluge",
  "type": "DELUGE_V2",
  "enabled": true,
  "host": "127.0.0.1",
  "port": 12064,
  "tls": false,
  "tls_skip_verify": false,
  "username": "USERNAME",
  "password": "PASSWORD",
  "settings": {
    "basic": {},
    "rules": {
      "enabled": true,
      "max_active_downloads": 2,
    }
  }
}'
```

```bash title="*arr"
curl -X POST 'http://127.0.0.1:7474/api/download_clients' -H 'X-API-Token: AUTOBRR_API_KEY' \
-d '{
  "name": "Sonarr",
  "type": "SONARR",
  "enabled": true,
  "host": "http://sonarr:9989/sonarr",
  "settings": {
    "apikey": "ARR_API_KEY",
    "basic": {
      "auth": true,
      "username": "USERNAME",
      "password": "PASSWORD"
    },
    "external_download_client_id": 0
  }
}'
```

### Update existing download client

```bash title="qBittorrent"
curl -X PUT 'http://127.0.0.1:7474/api/download_clients' -H 'X-API-Token: AUTOBRR_API_KEY' \
-d '{
  "id": 21,
  "name": "Qbit",
  "type": "QBITTORRENT",
  "enabled": true,
  "host": "https://qbit.autobrr.com",
  "tls": true,
  "tls_skip_verify": true,
  "username": "USERNAME",
  "password": "NEW_PASSWORD",
  "settings": {
    "basic": {
      "auth": true,
      "username": "USERNAME",
      "password": "NEW_PASSWORD"
    },
    "rules": {
      "enabled": true,
      "max_active_downloads": 2,
      "ignore_slow_torrents": true,
      "download_speed_threshold": 10000,
      "upload_speed_threshold": 2000,
      "ignore_slow_torrents_condition": "ALWAYS or MAX_DOWNLOADS_REACHED"
    },
    "external_download_client_id": 1
  }
}'
```

```bash title="Deluge"
curl -X PUT 'http://127.0.0.1:7474/api/download_clients' -H 'X-API-Token: AUTOBRR_API_KEY' \
-d '{
  "id": 13,
  "name": "Deluge",
  "type": "DELUGE_V2",
  "enabled": false,
  "host": "127.0.0.1",
  "port": 12064,
  "tls": false,
  "tls_skip_verify": false,
  "username": "USERNAME",
  "password": "PASSWORD",
  "settings": {
    "basic": {},
    "rules": {
      "enabled": true,
      "max_active_downloads": 2,
      "ignore_slow_torrents": false,
      "download_speed_threshold": 0,
      "upload_speed_threshold": 0
    }
  }
}'
```

```bash title="*arrs"
curl -X PUT 'http://127.0.0.1:7474/api/download_clients' -H 'X-API-Token: AUTOBRR_API_KEY' \
-d '{
  "id": 21,
  "name": "Sonarr",
  "type": "SONARR",
  "enabled": true,
  "host": "http://sonarr4k:9990/sonarr4k",
  "settings": {
    "apikey": "ARR_API_KEY",
    "basic": {
      "auth": true,
      "username": "USERNAME",
      "password": "NEW_PASSWORD"
    },
    "external_download_client_id": 1
  }
}'
```

## Notifications

### List all notification agents

Retrieve a list of all notification agents configured in your autobrr instance.

```bash
curl -X GET 'http://127.0.0.1:7474/api/notification' -H 'X-API-Token: AUTOBRR_API_KEY' | jq '.[] | {id, name, type, enabled, events}'
```

### Create a new notification agent

```bash title="Notifiarr"
curl -X POST 'http://127.0.0.1:7474/api/notification' -H 'X-API-Token: AUTOBRR_API_KEY' \
-d '{
  "enabled": true,
  "type": "NOTIFIARR",
  "name": "Notifiarr Agent",
  "webhook": "",
  "events": [
    "PUSH_REJECTED",
    "PUSH_APPROVED",
    "PUSH_ERROR",
    "IRC_DISCONNECTED",
    "APP_UPDATE_AVAILABLE",
    "IRC_RECONNECTED"
  ],
  "api_key": "NOTIFIARR_API_KEY"
}'
```

```bash title="Discord"
curl -X POST 'http://127.0.0.1:7474/api/notification' -H 'X-API-Token: AUTOBRR_API_KEY' \
-d  '{
  "enabled": true,
  "name": "Discord Agent",
  "type": "DISCORD",
  "enabled": true,
  "events": [
    "PUSH_APPROVED"
  ],
  "webhook": "https://discord-webhook.url"
}'
```

```bash title="Telegram"
curl -X POST 'http://127.0.0.1:7474/api/notification' -H 'X-API-Token: AUTOBRR_API_KEY' \
-d '{
  "enabled": true,
  "type": "TELEGRAM",
  "name": "Telegram Agent",
  "events": [
    "PUSH_REJECTED",
    "PUSH_APPROVED"
  ],
  "token": "BOT_TOKEN",
  "channel": "CHAT_ID",
  "topic": "MESSAGE_THREAD_ID"
}'
```

```bash title="Gotify"
curl -X POST 'http://127.0.0.1:7474/api/notification' -H 'X-API-Token: AUTOBRR_API_KEY' \
-d '{
  "enabled": true,
  "type": "GOTIFY",
  "name": "Gotify Agent",
  "events": [
    "PUSH_ERROR"
  ],
  "host": "https://gotify.url",
  "token": "APP_TOKEN"
}'
```

```bash title="Pushover"
curl -X POST 'http://127.0.0.1:7474/api/notification' -H 'X-API-Token: AUTOBRR_API_KEY' \
-d '{
  "enabled": true,
  "type": "PUSHOVER",
  "name": "Pushover Agent",
  "events": [
    "APP_UPDATE_AVAILABLE"
  ],
  "api_key": "PUSHOVER_API_KEY",
  "token": "USER_KEY"
}'
```

## API keys

### List all API keys

Retrieve a list of all API keys in your autobrr instance.

```bash
curl -X GET 'http://127.0.0.1:7474/api/keys' -H 'X-API-Token: AUTOBRR_API_KEY' | jq 'map(del(.scopes))'
```

### Create a new API key

```bash
curl -X POST 'http://127.0.0.1:7474/api/keys' -H 'X-API-Token: AUTOBRR_API_KEY' \
-d '{"name":"name your key","scopes":[]}' | jq 'del(.scopes)'
```

## Release history

### Search release history

The release list supports filtering by free-text query, indexer and push status.

```bash
curl -X GET 'http://127.0.0.1:7474/api/release?q=1080p&indexer=redacted&push_status=PUSH_APPROVED&limit=20' -H 'X-API-Token: AUTOBRR_API_KEY' | jq
```

### Clear release history

Remove release history entries that are older than a specified number of hours.

```bash
curl -X DELETE 'http://127.0.0.1:7474/api/release?olderThan=8760' -H 'X-API-Token: AUTOBRR_API_KEY'
```

The delete can also be scoped with `indexer` and `releaseStatus` parameters, for example to remove only rejected entries for one indexer:

```bash
curl -X DELETE 'http://127.0.0.1:7474/api/release?olderThan=720&indexer=redacted&releaseStatus=PUSH_REJECTED' -H 'X-API-Token: AUTOBRR_API_KEY'
```

Scheduled cleanups can be managed in the UI or via the `/release/cleanup-jobs` endpoints, see [Release history cleanup](./usage/search.mdx#release-history-cleanup).

## Config

### Read the config

```bash
curl -X GET 'http://127.0.0.1:7474/api/config' -H 'X-API-Token: AUTOBRR_API_TOKEN' | jq
```

### Change log level

```bash
curl -X PATCH 'http://127.0.0.1:7474/api/config' -H 'X-API-Token: AUTOBRR_API_TOKEN' -d '{
    "log_level": "TRACE"
}'
```

### Enable or disable update check

```bash
curl -X PATCH 'http://127.0.0.1:7474/api/config' -H 'X-API-Token: AUTOBRR_API_TOKEN' -d '{
    "check_for_updates": true
}'
```

The same `PATCH /api/config` endpoint also accepts `log_path`.

---

## Community


The docs cover the common questions, but some things are easier to figure out by asking someone who runs the same setup as you. That's what the community is for.

## Discord

Most of the community lives on [Discord](https://discord.autobrr.com/), with over 5,500 members. It's the fastest way to get help with your setup, and a good place to hang out even when nothing is broken: filter tips, tracker talk, seedbox and automation chat, and plenty of people who care about the same niche things you do. The developers are active there too.

[Join the Discord](https://discord.autobrr.com/)

## IRC

For a project built around IRC, it would be strange not to have a channel of our own. We run our own IRC server:

|             |                   |
|-------------|-------------------|
| **Server**  | `irc.autobrr.com` |
| **Port**    | `6697` (TLS)      |
| **Channel** | `#chat`           |

Point your favorite IRC client at it and say hi.

---

## Authentication

## Built-in Authentication {/* #built-in-authentication */}

The built-in authentication is enabled by default and uses a username/password combination. When you first access autobrr, you'll be prompted to create an account.

autobrr supports a single user account. If you need more identities, use an OIDC provider; all logins share the same autobrr instance and data.

## Sessions {/* #sessions */}

Sessions last 30 days and are automatically extended while in use (renewal happens when a session is within 7 days of expiring). The **Remember me** checkbox on the login page, checked by default, controls whether the session cookie persists across browser restarts.

Sessions are stored in the database, so they survive autobrr restarts. Logging out destroys the session server-side.

## OpenID Connect (OIDC) {/* #openid-connect-oidc */}

autobrr supports OIDC authentication for integration with external identity providers like [Authentik](https://goauthentik.io/), [Authelia](https://www.authelia.com/), [Pocket-ID](https://github.com/stonith404/pocket-id), and more.

### Configuration {/* #configuration */}

#### 1. Configure your identity provider {/* #configure-your-identity-provider */}

1. Set up a new application/client in your identity provider
2. Set the redirect URI to: `https://your-autobrr-instance/api/auth/oidc/callback`
3. Note down the client ID and client secret

:::tip[Authentik-specific configuration]

When using Authentik, configure the following:

- Use RS256 signing algorithm
- Under Protocol Settings, select an RSA "Signing Key" (e.g., the Authentik self-signed certificate)

For more details on Authentik setup, see:

- [Authentik RS256 Configuration](https://github.com/goauthentik/authentik/issues/9250)
- [Authentik Certificate Documentation](https://docs.goauthentik.io/docs/sys-mgmt/certificates#default-certificate)
- [autobrr OIDC Setup Example](https://github.com/autobrr/autobrr/pull/1853#issuecomment-2543410055)

:::

#### 2. Enable OIDC in autobrr {/* #enable-oidc-in-autobrr */}

Choose one of these configuration methods:

```toml title="config.toml"
oidcEnabled = true
oidcIssuer = "https://your-identity-provider"
oidcClientId = "your-client-id"
oidcClientSecret = "your-client-secret"
oidcRedirectUrl = "https://your-autobrr-instance/api/auth/oidc/callback"
oidcDisableBuiltInLogin = false
```

Or using environment variables:

```env
AUTOBRR__OIDC_ENABLED=true
AUTOBRR__OIDC_ISSUER=https://your-identity-provider
AUTOBRR__OIDC_CLIENT_ID=your-client-id
AUTOBRR__OIDC_CLIENT_SECRET=your-client-secret
AUTOBRR__OIDC_REDIRECT_URL=https://your-autobrr-instance/api/auth/oidc/callback
AUTOBRR__OIDC_DISABLE_BUILT_IN_LOGIN=false
```

:::info[Authentication Methods]
When OIDC is enabled:

- If you have an existing user in the database, both OIDC and built-in authentication will be available
- If no user exists in the database, only OIDC authentication will be available
  :::

:::info[PKCE]
autobrr automatically uses the Authorization Code Flow with PKCE (S256) when your identity provider advertises support for it in its discovery document. Providers that require PKCE (like Pocket-ID) work out of the box with no extra configuration.
:::

## Troubleshooting {/* #troubleshooting */}

During testing, we used [Authelia](https://www.authelia.com/), [Authentik](https://goauthentik.io/), and [Pocket-ID](https://github.com/stonith404/pocket-id) with success. Each provider has been verified to work with autobrr's OIDC implementation.

autobrr starts even when the identity provider is unreachable: OIDC discovery retries in the background (every 5 seconds for roughly 4 minutes), which covers docker-compose setups where the identity provider comes up after autobrr. Issuer URLs are also tried both with and without a trailing slash, so a slash mismatch between your config and the provider's discovery document is handled automatically.

If you encounter issues, please open a [GitHub issue](https://github.com/autobrr/autobrr/issues/new?template=bug_report.md) or reach out to us on [Discord](https://discord.autobrr.com/).

## Security Best Practices {/* #security-best-practices */}

1. Always run autobrr behind a reverse proxy with TLS enabled
2. Make sure the proxy forwards `X-Forwarded-Proto: https`. autobrr cannot serve TLS itself and only marks the session cookie as Secure when this header is present; OIDC callback redirects also rely on it.
3. Use strong passwords for built-in authentication
4. Enable MFA in your identity provider when using OIDC
5. Regularly update both autobrr and your identity provider

For reverse proxy setup instructions, see:

- [Caddy](../installation/reverse-proxy/caddy)
- [Lighttpd](../installation/reverse-proxy/lighttpd)
- [Nginx](../installation/reverse-proxy/nginx)
- [SWAG](../installation/reverse-proxy/swag)
- [Traefik](../installation/reverse-proxy/traefik)
- [Tailscale Serve](../installation/reverse-proxy/tailscale-serve)

---

## Configuring autobrr

The primary configuration entry point for autobrr is `config.toml`, which should be located in the `--config` directory you specified to the autobrr process or in the `config/` directory relative from which autobrr is running. Do note that you do not need to create it yourself, as the autobrr daemon will do it automatically for you in case it does not exist upon first start.

```toml title="config.toml"
# config.toml

# Hostname / IP
#
# Default: "localhost"
#
host = "127.0.0.1"

# Port
#
# Default: 7474
#
port = 7474

# Base url
# Set custom baseUrl eg /autobrr/ to serve in subdirectory.
# Not needed for subdomain, or by accessing with the :port directly.
#
# Optional
#
#baseUrl = "/autobrr/"

# Base url mode legacy (added in v1.55.0)
# This is kept for compatibility with older versions doing url rewrite on the proxy.
# If you use baseUrl you can set this to false and skip any url rewrite in your proxy.
#
# Default: true
#
baseUrlModeLegacy = true

# autobrr logs file
# If not defined, logs to stdout
#
# Optional
#
#logPath = "log/autobrr.log"

# Log level
#
# Default: "DEBUG"
#
# Options: "ERROR", "DEBUG", "INFO", "WARN", "TRACE"
#
logLevel = "DEBUG"

# Log Max Size
#
# Default: 50
#
# Max log size in megabytes
#
#logMaxSize = 50

# Log Max Backups
#
# Default: 3
#
# Max amount of old log files
#
#logMaxBackups = 3

# Check for updates
#
# Default: true
#
checkForUpdates = true

# Database DSN
# Optional. Can be used instead of databaseType and the individual postgres* fields.
# Accepts postgres:// / postgresql:// URLs or a SQLite file path.
#
#databaseDSN = "postgresql://autobrr:postgres@localhost:5432/autobrr?sslmode=disable"

# Database Max Backups
# autobrr automatically backs up the SQLite database before schema migrations.
# Set to 0 to disable (config file only, the env var cannot disable it).
#
# Default: 5
#
#databaseMaxBackups = 5

# CORS allowed origins
# Comma separated list of origins allowed to call the API from a browser.
#
# Default: "*"
#
#corsAllowedOrigins = "*"

# Go pprof profiling (for debugging)
#
# Default: false, "127.0.0.1", 6060
#
#profilingEnabled = false
#profilingHost = "127.0.0.1"
#profilingPort = 6060

# OpenID Connect Configuration
#
# Enable OIDC authentication
#oidcEnabled = false
#
# OIDC Issuer URL (e.g. https://auth.example.com)
#oidcIssuer = ""
#
# OIDC Client ID
#oidcClientId = ""
#
# OIDC Client Secret
#oidcClientSecret = ""
#
# OIDC Redirect URL (e.g. http://localhost:7474/api/auth/oidc/callback)
#oidcRedirectUrl = ""
#
# Disable Built In Login Form (only works when using external auth)
#oidcDisableBuiltInLogin = false

# Metrics
#
# Enable metrics endpoint
#metricsEnabled = true

# Metrics server host
#
#metricsHost = "127.0.0.1"

# Metrics server port
#
#metricsPort = 9074

# Metrics basic auth
#
# Comma separate list of user:password. Password must be htpasswd bcrypt hashed. Use autobrrctl to generate.
# Only enabled if correctly set with user:pass.
#
#metricsBasicAuthUsers = ""

# Custom definitions
#
#customDefinitions = "/home/$YOUR_USER/.config/autobrr/definitions"
```

#### Config options {/* #config-options */}

- `host`: If not using a reverse proxy or in a container, change to `0.0.0.0`.
- `port`: If port already in use, then change to a free one.
- `logLevel`: Choose how much log output you want to see. Changes to `config.toml` are picked up automatically without a restart, and the level can also be changed on the fly under **Settings > Logs** in the web UI.
- (**optional**) `baseUrl`: Supports running on both the root url and in a subpath, as well as subdomain. Uncomment if needed.
- (**optional**) `baseUrlModeLegacy`: (Added in v1.55.0) When set to false, no URL rewrite is needed in your proxy configuration. Set to true to maintain compatibility with older proxy configurations that use URL rewrites.
- (**optional**) `logPath`:Considering autobrr is rather new software, it might be beneficial for logging to be enabled. If running with systemd you can use `journalctl` to check logs. The log file is rotated as soon as it reaches 50MB, up to 3 times. In other words, the maximum space which the log files can occupy is 150MB, which takes a long time to fill.
- (**optional**) `databaseMaxBackups`: autobrr backs up the SQLite database before every schema migration; the backup files appear next to the database as `autobrr.db_svN_<timestamp>.backup`. This option controls how many are kept (default 5).
- (**optional**) `corsAllowedOrigins`: Comma separated list of origins allowed to call the API from a browser, for setups with third-party frontends. Default `*`.
- (**optional**) `profilingEnabled` / `profilingHost` / `profilingPort`: Exposes Go pprof endpoints for debugging, disabled by default. Only enable when asked to while troubleshooting.

### Metrics (Prometheus) {/* #metrics */}

Metrics are disabled by default. With `metricsEnabled = true`, autobrr serves Prometheus metrics on a separate listener at `http://<metricsHost>:<metricsPort>/metrics` (default `127.0.0.1:9074`), independent of the web UI port. The exported metrics are prefixed `autobrr_` and cover releases, IRC, feeds, lists and filters.

```yaml title="prometheus.yml"
scrape_configs:
  - job_name: autobrr
    static_configs:
      - targets: ["127.0.0.1:9074"]
```

The endpoint can be protected with basic auth via `metricsBasicAuthUsers` (comma separated `user:password` pairs with the password bcrypt-hashed, generated with [`autobrrctl htpasswd`](#autobrrctl)).

### Create user via command line (optional) {/* #create-user-via-cli */}

This step is not needed unless you wish to create a user _via the command line_. Instead, the process of creating a user can be done via the web UI instead, which is the recommended way to do it.

To create a user alongside the initial database, you need to use `autobrrctl`. Specify your config directory via the `--config` argument, followed by `create-user` and then your wanted username. After executing the command, you will prompted to enter a password.

Example:

```shell
autobrrctl --config ~/.config/autobrr create-user USERNAME
```

### Other autobrrctl commands {/* #autobrrctl */}

`autobrrctl` has a few more commands worth knowing about:

- `autobrrctl --config <dir> export-filters`: Exports every filter to individual JSON files, handy for backups or sharing.
- `autobrrctl htpasswd`: Prompts for a password and prints the bcrypt hash needed for `metricsBasicAuthUsers`. Not listed in the built-in help text.
- `autobrrctl version`: Prints the autobrrctl version.
- `autobrrctl db:convert`: Converts a SQLite database to PostgreSQL, see the [PostgreSQL guide](../installation/supplementary/postgresql.mdx#convert).
- `autobrrctl db:seed --db-path <path> --seed-db <file>` and `autobrrctl db:reset`: Database seeding and reset, mainly for development and testing.

## Other options {/* #other-options */}

Make sure to read through all of the articles as all of them have some important information on how to get autobrr up and running.

- [Indexers ](./indexers.mdx)
- [IRC ](./irc.mdx)
- [Download Clients ](./download-clients/dedicated)
- [Feeds (RSS / Torznab / Newznab) ](./feeds.mdx)

## Additional help {/* #additional-help */}

If you're having any trouble with the documentation, join us at [Discord ](https://discord.autobrr.com/) and we will do our best to help.

If you have found a bug or are having an issue, please open an issue on [GitHub ](https://github.com/autobrr/autobrr/issues/)

---

## Download Clients


Go to `Settings > Clients` to setup clients.
Clients can be local or remote, as long as ports are open and auth available.

These are the available download clients.

- qBittorrent
- Deluge (v1+ and v2+)
- rTorrent / ruTorrent
- Transmission
- Porla
- aria2
- Sabnzbd (Usenet)
- NZBGet (Usenet)
- Radarr
- Sonarr
- Lidarr
- Readarr
- Whisparr

All clients have a test function to try out the connection details before saving.

Don't forget to give the client a name!

## Configure Download Clients {/* #configure-download-clients */}

## qBittorrent {/* #qbittorrent */}

You can run autobrr and qBittorrent on the following setups.

- Local server
- Remote server
- Docker / container

### Local {/* #qbittorrent-local */}

For a local client, meaning autobrr and qBittorrent **on the same server** then this should work. Check qBittorrent settings to get the `WEBUI_PORT`.

- Host: `http://127.0.0.1:WEBUI_PORT`
- TLS: disabled
- Username: `<username>`
- Password: `<password>`

### Remote {/* #qbittorrent-remote */}

For a remote client, meaning autobrr and qBittorrent are **not on the same server** then things might be a bit different.

- Host: `https://myserver.brr/qbittorrent`
- TLS: enabled
- Skip TLS verification: disabled (try this first)
- Username: `<username>`
- Password: `<password>`

Some setups like **Swizzin** requires to also use **Basic Auth** when connecting to it from a remote server.

- Basic Auth: enabled
- Username: `<username>`
- Password: `<password>`

### Docker {/* #qbittorrent-docker */}

With **Docker** / containers make sure autobrr and qBittorrent share the same network to be able to use the `container_name` as address.

- Host: `http://qbittorrent:WEBUI_PORT`
- TLS: disabled
- Username: `<username>`
- Password: `<password>`

:::info
qBittorrent can also be authenticated with an optional **API key** instead of username and password, for WebUIs set up with API key authentication. Requires qBittorrent v5.2.x+
:::

## qBittorrent rules {/* #qbittorrent-rules */}

You can define some basic rules which can improve your performance for racing etc.

- **Enabled**: Disabled by default.
- **Max active downloads**: Default 0 (unlimited). Limit the amount of active downloads, to give the maximum amount of bandwidth and disk for the downloads.
- **Ignore slow torrents**: Disabled by default.
- **Ignore condition**: When the slow-torrent check runs.
  - `Max downloads reached`: speed thresholds are only checked once Max active downloads is hit.
  - `Always`: speed thresholds are checked on every push, regardless of the number of active downloads.
- **Download speed threshold**: If the total download speed is below this limit when the check runs, download anyway. Unit in KB/s.
- **Upload speed threshold**: If the total upload speed is below this limit when the check runs, download anyway. Unit in KB/s.

## Deluge {/* #deluge */}

You can run autobrr and Deluge on the following setups.

- Local server
- Remote server
- Docker / container

Deluge is split into two versions:

- `Deluge` which is v1 like `1.3.15`
- `Deluge 2` which is v2 like `2.0.0+`

Select `TYPE` then set these.

### Local {/* #deluge-local */}

For a local client, meaning autobrr and Deluge **on the same server** then this should work. Check Deluge settings to get the `DAEMON_PORT`.

- Host: `127.0.0.1`
- Port: `DAEMON_PORT`
- TLS: disabled
- Username: `<username>`
- Password: `<password>`

### Remote {/* #deluge-remote */}

For a remote client, meaning autobrr and Deluge are **not on the same server** then things might be a bit different.

- Host: `myserver.brr`
- Port: `DAEMON_PORT`
- TLS: disabled
- Username: `<username>`
- Password: `<password>`

:::info
autobrr connects directly to the Deluge daemon (the same connection a thin client uses), not to the Deluge web UI, so there is no Basic Auth option for Deluge. Use the daemon port and daemon credentials from `auth`, not the web UI password.
:::

### Docker {/* #deluge-docker */}

With **Docker** / containers make sure autobrr and Deluge share the same network to be able to use the `container_name` as address.

- Host: `deluge`
- Port: `DAEMON_PORT`
- TLS: disabled
- Username: `<username>`
- Password: `<password>`

## Deluge rules {/* #deluge-rules */}

You can define some basic rules which can improve your performance for racing etc.

- **Enabled**: Disabled by default.
- **Max active downloads**: Default 0 (unlimited). Limit the amount of active downloads, to give the maximum amount of bandwidth and disk for the downloads.

## rTorrent / ruTorrent {/* #rtorrent--rutorrent */}

You can run autobrr and rTorrent / ruTorrent on the following setups.

- Local server
- Remote server
- Docker / container

:::info
When Auth is enabled you can pick the **Auth type**: `Basic Auth` or `Digest Auth`. Basic Auth is correct in most cases, but some providers (like RapidSeedbox) use Digest Auth.
:::

### Local {/* #rtorrent-local */}

For a local client, meaning autobrr and ruTorrent **on the same server** try these.

Here are a couple of common ways for how to access ruTorrent.

- Host: `http://127.0.0.1/rutorrent/plugins/httprpc/action.php`
- Host: `http://localhost/rutorrent/plugins/httprpc/action.php`
- Host: `http://localhost/RPC2`

- TLS: disabled
- Basic Auth: enabled
- Username: `<username>`
- Password: `<password>`

If you are on a shared seedbox you might need your username in the url like:

- Host: `http://localhost/USERNAME/rutorrent/plugins/httprpc/action.php`

#### Swizzin {/* #rtorrent-local-swizzin */}

- Host: `https://127.0.0.1/rutorrent/plugins/httprpc/action.php`
- TLS: enabled
- Skip TLS verification: enabled
- Basic Auth: enabled
- Username: `<username>`
- Password: `<password>`

### Remote {/* #rtorrent-remote */}

For a remote client, meaning autobrr and rTorrent are **not on the same server** then things might be a bit different.

- Host: `http://EXTERNAL_IP/rutorrent/plugins/httprpc/action.php`
- Host: `http://mydomain.com/rutorrent/plugins/httprpc/action.php`
- TLS: disabled
- Basic Auth: enabled
- Username: `<username>`
- Password: `<password>`

### Docker {/* #rtorrent-docker */}

With **Docker** / containers make sure autobrr and rTorrent share the same network to be able to use the `container_name` as address.

- Host: `http://rtorrent/rutorrent/plugins/httprpc/action.php`
- TLS: disabled
- Basic Auth: enabled
- Username: `<username>`
- Password: `<password>`

## Transmission {/* #transmission */}

You can run autobrr and Transmission on the following setups.

- Local server
- Remote server
- Docker / container

### Local {/* #transmission-local */}

For a local client, meaning autobrr and Transmission **on the same server** then this should work. Check Transmission settings to get the `WEBUI_PORT`. Default is 9091.

- Host: `http://127.0.0.1:9091/transmission`
- TLS: disabled
- Username: `<username>`
- Password: `<password>`

### Remote {/* #transmission-remote */}

For a remote client, meaning autobrr and Transmission are **not on the same server** then things might be a bit different.

- Host: `http://myserver.brr/transmission` or `http://IP:PORT/transmission`
- TLS: enabled
- Skip TLS verification: disabled (try this first)
- Username: `<username>`
- Password: `<password>`

HTTPS / TLS

- Host: `https://myserver.brr/transmission`
- TLS: enabled
- Skip TLS verification: disabled (try this first)
- Username: `<username>`
- Password: `<password>`

### Docker {/* #transmission-docker */}

With **Docker** / containers make sure autobrr and Transmission share the same network to be able to use the `container_name` as address.

- Host: `http://transmission:9091` or `http://transmission:9091/transmission`
- TLS: disabled
- Username: `<username>`
- Password: `<password>`

## Transmission rules {/* #transmission-rules */}

You can define some basic rules which can improve your performance for racing etc.

- **Enabled**: Disabled by default.
- **Max active downloads**: Default 0 (unlimited). Limit the amount of active downloads, to give the maximum amount of bandwidth and disk for the downloads.

## Porla {/* #porla */}

Connects to the Porla web API.

- Host: `http(s)://host:port`
- Auth token: `<token>` (required, generate it in Porla)
- TLS: enable for `https://` hosts, with **Skip TLS verification** available for self-signed certificates

Some setups also require **Basic Auth** with a username and password, like other clients behind an HTTP-auth proxy.

## Porla rules {/* #porla-rules */}

You can define some basic rules which can improve your performance for racing etc.

- **Enabled**: Disabled by default.
- **Max active downloads**: Default 0 (unlimited). Limit the amount of active downloads, to give the maximum amount of bandwidth and disk for the downloads.

## aria2 {/* #aria2 */}

Connects to the aria2 JSON-RPC endpoint.

- Host: `http://localhost:6800`, or `http(s)://domain.ltd/aria2` for reverse-proxied setups
- RPC secret: `<secret>` (optional, the value of aria2's `--rpc-secret` option; leave empty if aria2 runs without one)
- TLS: enable for `https://` hosts, with **Skip TLS verification** available for self-signed certificates

Some setups also require **Basic Auth** with a username and password, like other clients behind an HTTP-auth proxy.

## aria2 rules {/* #aria2-rules */}

You can define some basic rules which can improve your performance for racing etc.

- **Enabled**: Disabled by default.
- **Max active downloads**: Default 0 (unlimited). Limit the amount of active downloads, to give the maximum amount of bandwidth and disk for the downloads.

## SABnzbd {/* #sabnzbd */}

You can run autobrr and SABnzbd on the following setups.

- Local server
- Remote server

### Local {/* #sabnzbd-local */}

For a local client, meaning autobrr and SABnzbd **on the same server** then this should work. Check SABnzbd settings to get the `SABNZBD_PORT`.

- Host: `http://127.0.0.1:SABNZBD_PORT`
- TLS: disabled
- API key

### Remote {/* #sabnzbd-remote */}

For a remote client, meaning autobrr and SABnzbd are **not on the same server** then things might be a bit different.

- Host: `https://myserver.brr/sabnzbd`
- TLS: enabled
- API key

Some setups like **Swizzin** requires to also use **Basic Auth** when connecting to it from a remote server.

- Basic Auth: enabled
- Username: `<username>`
- Password: `<password>`

## NZBGet {/* #nzbget */}

You can run autobrr and NZBGet on the following setups.

- Local server
- Remote server

### Local {/* #nzbget-local */}

For a local client, meaning autobrr and NZBGet **on the same server** then this should work. Check NZBGet settings to get the `NZBGET_PORT`.

- Host: `http://127.0.0.1:NZBGET_PORT`
- Username: `<username>`
- Password: `<password>`

### Remote {/* #nzbget-remote */}

For a remote client, meaning autobrr and NZBGet are **not on the same server** then things might be a bit different.

- Host: `https://myserver.brr/nzbget`
- Username: `<username>`
- Password: `<password>`

:::info
There is no TLS toggle for NZBGet - whether the connection uses https is decided by the scheme of the Host URL (`http://` or `https://`).
:::

## Sonarr {/* #sonarr */}

You can run autobrr and Sonarr apps on the following setups.

- Local server
- Remote server
- Docker / container

:::info
All arr clients also have **TLS** and **Skip TLS verification** toggles (enable skip-verify for self-signed certificates), and an optional **Basic Auth** setting for instances behind an HTTP-auth proxy.
:::

### Local {/* #sonarr-local */}

For a local client, meaning autobrr and Sonarr **on the same server** then this should work.

- Host: `http://127.0.0.1:8989`
- API Key: `API KEY`

On **Swizzin** or if you are running Sonarr with a baseUrl set that in the url as well like:

- Host: `http://127.0.0.1:8989/sonarr`

### Remote {/* #sonarr-remote */}

For a remote client, meaning autobrr and Sonarr are **not on the same server** then things might be a bit different.

- Host: `http://mydomain.com:8989` or `https://mydomain.com/sonarr`
- API Key: `API KEY`

On **Swizzin** or if you are running Sonarr with a baseUrl set that in the url as well like:

- Host: `https://mydomain.com/sonarr`

### Docker {/* #sonarr-docker */}

With **Docker** / containers make sure autobrr and Sonarr share the same network to be able to use the `container_name` as address.

- Host: `http://sonarr:8989`
- API Key: `API KEY`

## Radarr {/* #radarr */}

You can run autobrr and Radarr apps on the following setups.

- Local server
- Remote server
- Docker / container

### Local {/* #radarr-local */}

For a local client, meaning autobrr and Radarr **on the same server** then this should work.

- Host: `http://127.0.0.1:7878`
- API Key: `API KEY`

On **Swizzin** or if you are running Radarr with a baseUrl set that in the url as well like:

- Host: `http://127.0.0.1:7878/radarr`

### Remote {/* #radarr-local */}

For a remote client, meaning autobrr and Radarr are **not on the same server** then things might be a bit different.

- Host: `http://mydomain.com:7878` or `https://mydomain.com/radarr`
- API Key: `API KEY`

On **Swizzin** or if you are running Radarr with a baseUrl set that in the url as well like:

- Host: `https://mydomain.com/radarr`

### Docker {/* #radarr-docker */}

With **Docker** / containers make sure autobrr and Radarr share the same network to be able to use the `container_name` as address.

- Host: `http://radarr:7878`
- API Key: `API KEY`

## Lidarr {/* #lidarr */}

See Radarr and Sonarr but port `8686`.

## Readarr {/* #readarr */}

See Radarr and Sonarr but port `8787`.

## Whisparr {/* #whisparr */}

See Radarr and Sonarr but port `6969`.

---

## Connecting to download clients on a shared seedbox

# Download Clients

Go to `Settings > Clients` to setup clients.
All clients have a test function to try out the connection details before saving. Don't forget to give the client a name!

## Shared seedbox providers

These are confirmed working ways to connect to download clients on various shared seedbox providers.
If you have information about other providers, please edit this page or let us know on Discord.

### qBittorrent

### Deluge

### rTorrent

:::caution
Some ambiguous characters (such as @ : # % and more) may escape out of the URL.  
In this case you will have to change your password for ruTorrent to be able to add the client to autobrr.
:::

### Transmission

### Sonarr

### Radarr

### Lidarr

### Readarr

### SABnzbd

### NZBGet

---

## Feeds

Some indexers does not have an IRC announce channel.
Luckily, most of them have RSS support.
You will treat Torznab/Newznab and RSS feeds as regular indexers when setting up your filters.

autobrr polls the feed on an interval, remembers what it has already seen, and runs only the new items through your filters, exactly like an IRC announce:

## Torznab / Newznab

Torznab and Newznab is essentially like browsing the torrents page, but automated and unified.

Prowlarr and Jackett are supported. We recommend that you use Prowlarr.

Go to `Settings > Indexers` and add `Generic Torznab` or `Generic Newznab` from the list.

- **Name**: `<name of indexer>`
- **Torznab/Newznab URL**: `http://localhost:port/ID/api`
- **API Key**: `<API key>`
- **Download type**: `Torrent` or `Magnet` (Torznab only - Newznab feeds have no download type and are always handled as NZB/usenet)

Once saved, head over to `Settings > Feeds` to enable it.

autobrr will get up to 50 items per refresh from the Torznab/Newznab feed (or the maximum the indexer advertises in its capabilities). On first run it will check all and cache the entries, on the second run it will check for any new entries and run them through the assigned filters.

Torznab feeds carry the `downloadvolumefactor` attribute, so the [Freeleech and Freeleech Percent](../filters/advanced.mdx) filter fields work with Torznab feeds (e.g. via Prowlarr), even for indexers whose IRC announces have no freeleech info.

### Categories

After saving a Torznab or Newznab feed, edit it under `Settings > Feeds` and click **Fetch** under Categories to pull the indexer's capabilities. Tick the categories you want; only the ticked category IDs are requested on each refresh, which reduces noise and load on the indexer. With no categories ticked, all categories are requested.

:::tip
The `ID` part of the URL is the number given to the indexer by Prowlarr.
You can see which number it is in Prowlarr by clicking the Indexer Name and viewing it in the info box.

The `/api` part of the URL is not to be confused with `<API key>` in the field below it.
:::

## RSS

Find the RSS feature of your indexer and grab the RSS link.

Go to `Settings > Indexers` and add `Generic RSS` from the list.

- **Name**: `<name of indexer>`
- **RSS URL**: `http://myindexer.com/rss`
- **Download type**: `Torrent`, `Magnet`, or `NZB` (NZB marks releases as usenet so they are sent to usenet download clients - useful for RSS feeds serving NZBs)
- **Cookie**: *optional* - for RSS feeds that require authentication, paste your site cookie (e.g. `uid=...; pass=...`). The same cookie is reused when downloading the .torrent files of matched releases.

Once saved, head over to `Settings > Feeds` to enable it.

autobrr will get the latest items from the RSS feed. On first run it will check all and cache the entries, on the second run it will check for any new entries and run them through the assigned filters.

autobrr extracts as much as it can from each feed item so your filters have data to work with: release size (from enclosures, the description text, or `torrent`/`ezrss` extension elements), seeders and leechers, info hash, magnet URI, categories, and basic freeleech detection when the word `freeleech` appears in the title or description.

## Feed settings

Every feed has a few settings under `Settings > Feeds`:

- **Refresh interval**: How often to fetch the feed, in minutes. Recommended 15-30; too low may risk a ban on some indexers.
- **Refresh timeout**: How long to wait for the indexer to answer before aborting a refresh, in seconds.
- **Max age**: Skip items published longer than this many seconds ago. Use `0` to disable the age check and process all items.
- **Skip TLS verification (insecure)**: For feeds served over HTTPS with self-signed or otherwise invalid certificates, e.g. a local Prowlarr or Jackett instance. Leave off unless needed, since it disables certificate validation.

## Clearing the feed cache

Since version `1.29` it is possible to clear the feed cache.
Head to **Settings** -> **Feeds** and click the three dots for the feed you want to clear.

![Clear feed cache](/img/feed_cache.png)

:::tip
Cached entries have a one month lifetime, and a daily maintenance job automatically removes long-expired and orphaned entries.
:::

## Force run feed

The Force run feed option allows you to manually trigger a feed refresh, providing you with the most up-to-date data outside the regular feed schedule.

![Force run feed](/img/force_run_feed.png)

:::caution
Be careful when using this feature and ensure that you adhere to the refresh interval rules defined by the indexers.
:::

---

## Indexers and trackers in autobrr

# Indexers

:::info
For adding more indexers to autobrr, please submit an [Indexer Request](https://github.com/autobrr/autobrr/issues/new/choose) on GitHub 
:::

## Supported Indexers {/* #supported-indexers */}

The list below of supported indexers are for indexers who have IRC announces. If your indexer is not in the list you can still use it via **Generic RSS** and **Generic Torznab/Newznab** (via Prowlarr or Jackett). See [Feeds](./feeds.mdx).

## Setup {/* #setup */}

Navigate to `Settings > Indexers` to add new indexers.

   When adding a new indexer, autobrr automatically configures the necessary IRC network and channels. Indexers usually need some extra keys to work. The common ones are:

   - `passkey`
   - `rsskey`
   - `torrent_pass`
   - `auth_key`
   - `apikey`

    Not all of these are required when setting up a new indexer. `Passkeys` and `torrent_pass` are typically found in the download url of a torrent, while `apikey`, `auth_key` and `rsskey`s are on your indexer's profile page. Check your indexers wiki/forum etc. if you're having trouble finding something specific, the question has been likely asked before and the staff probably already have their own guide on how to set up.

   For instance, TorrentLeech provides a setup guide [here](http://wiki.torrentleech.org/doku.php/autobrr).  

   :::info
   - If NickServ Password is marked with a `*`, a registered IRC account is required. Refer to [registering with NickServ](irc.mdx#registering-with-nickserv) for more details.
   - NickServ Account marked with a `*` indicates that it's utilized only for the nick but supports NickServ authentication.  
   - The `invite command` field under `Settings > IRC > Edit network` will come pre-populated. Input your IRC key here, and ensure the rest of the settings remain unchanged.
   :::

#### Activating the Network {/* #activating-the-network */}

Once your indexer is configured, go to `Settings > IRC` and flip the switch associated with the newly created network. Now is a good time to review all settings, including the invite command.

:::caution[Important]
Refer to the [IRC](../configuration/irc.mdx) section for detailed information about NickServ, IRC keys, and nick grouping.
:::

### External Identifier (optional) {/* #external-identifier */}

To enable features such as seed limits (seed ratio, seed time) when pushing releases to \*arrs, an `External identifier` is required. This identifier must correspond to the indexer name in your \*arr setup. If you are using Prowlarr, it will typically be listed as "TorrentLeech (Prowlarr)".

:::info
Available in verison `v1.42.0+`

This option will only appear when you **edit** an existing indexer.
:::

## Custom indexer definitions {/* #custom-indexer-definitions */}

autobrr supports custom indexer definitions.

In the autobrr config file, add the following to the bottom if it's not already there:

```toml
# Custom definitions
#
customDefinitions = "/home/$YOUR_USER/.config/autobrr/definitions"
```

Change `$YOUR_USER` to your username.

For Docker:

```toml
# Custom definitions
#
customDefinitions = "/config/definitions"
```

This should work if you have `/config` mapped to a volume which you hopefully have.

1. Create your definition file and place it in the directory specified in your config file.
2. Restart autobrr to apply changes.
3. Configure the new indexer by navigating to `Settings > Indexers` and setting it up as usual.

:::info[Definition format]
Current definitions after autobrr `v1.82.0` use `version: 2`, with per-channel `parse` blocks and named regex capture groups. Older custom definitions without a `version` field are treated as the legacy v1 format and still load through a compatibility layer.

The best starting point for a new definition is to copy a current one from the [official definitions directory](https://github.com/autobrr/autobrr/tree/develop/internal/indexer/definitions) and adapt it.
:::

---

## IRC

IRC stands for Internet Relay Chat. autobrr has its own IRC client built in which lets it monitor the #announce channels without the need for additional software.

## Prerequisites {/* #prerequisites */}

You need a registered nick on most IRC servers to be able to join channels. We will set up a registered user in a few easy steps.

You need a separate IRC client to do this.
Here are some free and open source options:

- [Konversation](https://konversation.kde.org/) - Linux
- [LimeChat](http://limechat.net/mac/) - MacOS
- [HexChat](https://hexchat.github.io/) - Windows/Linux
- [The Lounge](https://thelounge.chat) - A web based, self hosted option.

Make sure your indexer is supported before proceeding.

### Registering with NickServ {/* #registering-with-nickserv */}

When you first open the IRC client it usually tells you to set up your nickname and choose what server to connect to. You should preferably choose the username you use on the tracker(s) you want autobrr to monitor for this.

1. Connect to the IRC network using your IRC client of choice.
2. Register your nick with NickServ: `/msg nickserv register PASSWORD EMAIL`

The password should **not** match the one you use for logging in to the tracker.
The e-mail address doesn't have to match either.

:::caution
If you do not plan to use grouped nicks (read the next section), make sure to disconnect from the IRC server in your IRC client before attempting to set it up in autobrr.
:::

### Grouping nicks {/* #grouping-nicks */}

It is recommended to set up autobrr with a grouped IRC nick since you might want to talk in the other channels in a separate IRC client while autobrr monitors the #announce channel.

NickServ allows you to group two nicks to the same account in a few easy steps:

1. While connected to the IRC server with `username`, do `/nick USERNAME|AUTODL` to change to the nick you want autobrr to use.
2. Ask NickServ to group your nicks: `/msg nickserv group USERNAME PASSWORD`
3. Change back to your username: `/nick USERNAME`

You have now successfully grouped your nicks and can safely connect autobrr to the IRC network with `username|autodl` while using `username` in another IRC client if you want.

### Getting banned on IRC {/* #getting-banned-on-irc */}

In some rare occurrences your bot might get banned from the IRC network. This can happen if the network suddenly changes how people are allowed to connect for example.

Some networks won't require special authentication, while others do, but they could implement it at any time. If they do, and your bot isn't set up for it, it will just retry to join the channel into infinity on a set interval. The network owners might ban you in this case.

Usually these things can often be resolved by contacting their support. Most trackers have a #support channel as well as a ticket system on their site.

You shouldn't need to worry about it, but it's nice now to know what you need to do if that were to happen.

## Setup {/* #setup */}

The initial setup of IRC networks and channels are done during the setup of [indexers](../configuration/indexers.mdx).

If you for some reason need to setup a network manually, or edit an existing one, you can do that in `Settings > IRC`.

Before setup, make sure you have generated the necessary keys. Some networks have invite commands with extra keys. Some require you to be registered with NickServ (see [registering with NickServ](#registering-with-nickserv)). Trackers have documentation for the extra authentication protocols in their wiki pages.

- If NickServ Password is marked `*` as required, then you need to have a registered account on that IRC network. See [registering with NickServ](#registering-with-nickserv) above.
- If NickServ Account is marked `*` as required, that's only used as nick, but supports NickServ auth.
- The invite command field in `Settings > IRC > Edit network` are pre filled, but you need to add your IRC key. The rest should be left as is.

### Connect commands {/* #connect-commands */}

The invite/connect command field supports a bit of syntax worth knowing:

- Multiple commands can be chained with commas; each is sent as a message with a one second delay between them.
- Any `/msg` in the field is stripped, so both `/msg NickServ IDENTIFY key` and `NickServ IDENTIFY key` work.
- `/sleep N` (added in v1.76.0) pauses N seconds before the next command, useful for trackers that need a delay between authentication and the invite request. For example: `NickServ IDENTIFY key,/sleep 5,BotName !invite USERNAME IRCKEY`

### Network and channel settings {/* #network-settings */}

A few optional settings on the network form in `Settings > IRC > Edit network`:

- **TLS** and **Skip TLS verification (insecure)**: skip-verify is only for networks with self-signed or expired certificates and should otherwise stay off.
- **IRCv3 Bot Mode**: flags autobrr as a bot ([IRCv3 bot mode](https://ircv3.net/specs/extensions/bot-mode)) on networks that support it; ignored when the network does not.
- Each channel entry accepts an optional **channel password** (join key), needed by a few trackers with keyed announce channels.

:::caution[Caution]

Quite a few indexers use the same network, specifically `irc.p2p-network.net`.

- If you use the same nick with multiple indexers, it will reuse the same connection for them.
- If you have more than one nick on the same network in will create a new connection for each.

Adding or removing `indexers/networks/channels` can therefore break things.

:::

## Troubleshoot {/* #troubleshoot */}

If you have any issues with IRC not connecting or staying red then do the following:

1. Go into `Settings -> Logs` and set Level to `TRACE`
2. Go into `Settings -> IRC` and either hit the enabled toggle or click the thre dots button press the `Restart` option
3. Go to the `Logs` page and look what it is doing

There will be a lot of info with Trace logs so you'll have to read carefully. `NickServ` and `SASL` errors are related to auth and could mean you have not registered when it's required, or put in the wrong info.

### Live channel view and re-processing announces {/* #live-channel-view */}

Click a network in `Settings > IRC` to expand its channels with their status (monitoring since / last announce). The **View** button opens a live view of the messages in a channel as they arrive.

Next to each announce line there is a **Re-process announce** button that pushes that exact line through the filter pipeline again. This is the easiest way to test your filters against a real announce that was missed or rejected.

autobrr uses the **Auth Mechanism** `SASL` by default. Some networks does not support it and a change of **Auth Mechanism** to `NickServ` will generally fix it. Some does not require NickServ registration at all and then you can set it to `None`-

If you need some assistance then the best way to get help is [Discord](https://discord.autobrr.com/).

## Bouncing around (optional) {/* #bouncing-around-optional */}

:::warning

This is meant for advanced users or those that need a single irc connection for certain networks or for those using multiple servers with multiple autobrr instances.

:::

Due the current way of the release-parsing pipeline works, you may want to use a dedicated autobrr instance for your downloader. For this purpose, having a IRC bouncer in front will be beneficial, as it enables you to use the same irc-bot account for multiple autobrr instances. This still require you to have gone trough the above steps of setting up a bot account.

### Setting up ZNC {/* #setting-up-znc */}

:::info

There is some more info around the setup in this GitHub issue: https://github.com/autobrr/autobrr.com/issues/125

:::

This write-up will use the [Linuxserver ZNC](https://github.com/linuxserver/docker-znc) docker image.

```yml
---
version: "2.1"
services:
  znc:
    image: lscr.io/linuxserver/znc:latest
    container_name: znc
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
    volumes:
      - /path/to/data:/config
    ports:
      - 6501:6501
    restart: unless-stopped
```

This example will get you a working baseline, there will be some tips to enable SSL further down.

Theres two ways to configure ZNC, straight in irc, or trough the webui, this write-up will use the webui where possible.

Consult the containers readme for up-to-date info on the current default credentials(at the time of writing it is `admin/admin`), use these to log in to the webui on port 6501. Go to "Your Settings" on the menu on the top left, as you will want to change the default password, you can also change the default irc nick here. Save by selecting "Save and continue", as you want to stay on this page for the next step.

Now you want to set up the networks, the exact settings varies, fortunately autobrr´s irc definitions holds all the information you want. The write-up will use the current (as of writing) [definition for AR](https://github.com/autobrr/autobrr/blob/v1.29.0/internal/indexer/definitions/alpharatio.yaml).

You want to set `Network Name` to something recognizable as it is the identifier you will use when connecting to this network in autobrr. Set `Nickname`, `Alt. Nickname`, `Ident` and `Realname` to the bot nickname.

Leave `Active` to true, this way ZNC automatically connects to the network once it starts up.

Next up you want to add the server for this network, under the `Servers of this IRC network` section. Read the definition for the server, port and tls settings needed. For the linked definition, this will be line 30, 31 and 32 respectively.

You may need to enable some modules for the network based on the networks setup. You usually need either the [SASL](https://wiki.znc.in/Sasl) or [NickServ](https://wiki.znc.in/Nickserv) module. There is currently no way based on the definition to tell if a network supports SASL, so you might need to resort to NickServ. There is no reason to set up channels here, as autobrr will join the one specified in the definition (or send the private message needed), like it would without the bouncer.

#### Enabling SSL {/* #enabling-ssl */}

While this is not required, it might be easier to get going than you think. This section is based on already having Linuxserver´s SWAG generating a certificate for `znc.mydomain.com`, while keeping all traffic between containers inside the same docker network.

There is two changes that need to be done to the compose example to allow this to work.

```yml
version: "2.1"
services:
  znc:
    volumes:
      - /path-to-swag-config/etc:/swag-ssl
    networks:
      default:
        aliases:
          - znc.mydomain.com
```

This utilizes the [documented](https://github.com/linuxserver/docker-swag#using-certs-in-other-containers) way to share SWAGs certificates to other containers. To have DNS match, we tell docker to add a alias to the container using the domain we have a certificate for.

Before you apply this change, you also want to update the znc.conf in the persistent data of ZNC.

```ini
SSLCertFile = /swag-ssl/letsencrypt/live/<mydomain.com>/fullchain.pem
SSLDHParamFile = /swag-ssl/letsencrypt/live/<mydomain.com>/fullchain.pem
SSLKeyFile = /swag-ssl/letsencrypt/live/<mydomain.com>/privkey.pem
```

### Prepare the network {/* #prepare-the-network */}

While the SASL module offers a way to configure it in the webui, doing it over irc was easier, as you would need to do so for NickServ if SASL failed.

Connect to the network you set up in ZNC with your favorite client, like mentioned in the Prerequisites step. The IRC server is running on the same port as the webui in the default config for the Linuxserver image. For the username, use the bot nickname. The password tells ZNC which network you want to connect to, therefore it follows a preset syntax, there is some helper-text about this on the top of the network page in the webui. For this example it would be `admin/AlphaRatio:admin`.

Once connected to the ZNC network, you need to set up authentication.

#### SASL {/* #sasl */}

You can set up SASL by telling it about your bot username and password.

```text
/query *sasl Set <username> [<password>]
```

SASL is only negotiated on connection, so you need to tell ZNC to do a reconnect to the network.

```text
/query *status jump
```

If you are still not authenticated with the bot username, you need to use NickServ.

#### NickServ {/* #nickserv */}

To tell the module about your password, you use almost the same command as with SASL

```text
/query *nickserv set <password>
```

At this point you can disable/unload the module for the authentication method you are not using.

### Using the bouncer in Autobrr {/* #using-the-bouncer-in-autobrr */}

You tell autobrr to use the bouncer by toggling the `Bouncer (BNC)` switch in the IRC settings, this presents you with a field to enter the address of the bouncer, in `HOST:PORT` format, where host can be ip or a domain. You also need to to fill the password for the network with the same scheme(`admin/AlphaRatio:admin`) as you did when you connected your client to the bouncer.
Once you save these changes, you should now be able to confirm that the bouncer network is used, by looking at your network list in ZNC, it should now have increased the numbers of clients on the network.

---

## Notifications

autobrr can send notifications on the following events:

- Push Rejected (rejected by arr or download client rules)
- Push Approved (approved by arr or download client)
- Push Error (error when sending to download client)
- New Release (fires for every release received from an indexer, before filtering)
- IRC Disconnected (IRC disconnected unexpectedly)
- IRC Reconnected (IRC reconnected after disconnect)
- New update (new app update available)

:::caution
The New Release event triggers for **every** announce, before any filter matching. On busy indexers this can be extremely noisy.
:::

## Supported Agents

### Discord

:::warning
There is currently a bug when using the `Push Error` event.
It may leak your Download Client API/passkeys to the Discord channel. Keep that in mind if your Discord channel is accessible by others.
:::

To set up notifications for Discord, head to `Settings > Notifications`.

1. Click **Add new**.
2. Pick Discord from the list and give it a name.
3. Choose what events it should trigger on. You can enable all in the same agent or create separate agents for separate events.
4. Add your Webhook URL.
5. Click the `Test` button to try and send a test notification.
6. Save.

:::tip
Webhook URLs are created in Discord. Go to **Server Settings** in your Discord server and click **Integrations**, followed by **Webhooks**. Click **New Webhook** and follow the steps to copy the webhook URL.
:::

### LunaSea

To set up notifications for LunaSea, head to `Settings > Notifications`.

1. Click **Add new**.
2. Pick LunaSea from the list and give it a name.
3. Select what events to trigger on.
4. Add your `Webhook URL`
   - See [https://docs.lunasea.app/lunasea/notifications/custom-notifications](https://docs.lunasea.app/lunasea/notifications/custom-notifications)
5. Click the `Test` button to try and send a test notification.
6. Save.

### Notifiarr

To set up notifications for Notifiarr, head to `Settings > Notifications`.

1. Click **Add new**.
2. Pick Notifiarr in the list and give it a name.
3. Choose what events it should trigger on. You can enable all in the same agent or create separate agents for separate events.
4. Add your Notifiarr API key.
5. Click the `Test` button to try and send a test notification.
6. Save.

### Ntfy

Documentation: [Official docs](https://docs.ntfy.sh/).

To set up notifications for ntfy, head to `Settings > Notifications`.

1. Click **Add new**.
2. Pick ntfy in the list and give it a name.
3. Choose what events it should trigger on. You can enable all in the same agent or create separate agents for separate events.
4. Add your ntfy topic URL.
5. Authenticate with either username and password or an access token. If both are filled in, username and password are used.
6. Optionally add **Tags**: comma separated ntfy tags/emoji shortcodes shown on the notification, e.g. `download,arr,white_check_mark`.
7. Optionally set a **Priority** from 1 to 5 (ntfy's default is 3).
8. Click the `Test` button to try and send a test notification.
9. Save.

### Pushover

To set up notifications for Pushover, head to `Settings > Notifications`.

1. Click **Add new**.
2. Pick Pushover from the list and give it a name.
3. Choose what events it should trigger on. You can enable all in the same agent or create separate agents for separate events.
4. [Create an app](https://pushover.net/apps/build) with Pushover.
5. Fill in the app token and user key.
6. Optionally set a **Priority** from -2 to 2 (default 0). Priority 2 (emergency) requires acknowledgement and automatically retries every 60 seconds for up to an hour.
7. Optionally pick **Event sounds**: a default sound plus per-event overrides. The available sounds are fetched from your Pushover account.
8. Click the `Test` button to try and send a test notification.
9. Save.

### Gotify

To set up notifications for Gotify, head to `Settings > Notifications`.

1. Click **Add new**.
2. Pick Gotify from the list and give it a name.
3. Choose what events it should trigger on. You can enable all in the same agent or create separate agents for separate events.
4. Add your Gotify URL. Use the base server URL without the `/message` path, e.g. `https://gotify.example.com`; autobrr appends `/message` itself.
5. Add your `Application Token`
6. Click the `Test` button to try and send a test notification.
7. Save.

### Shoutrrr

Shoutrrr is a library that supports a lot of different notification services all in one. 

Supported services:

 - Bark
 - Discord
 - Email
 - Gotify
 - Google Chat
 - IFTTT
 - Join
 - Mattermost
 - Matrix
 - Ntfy
 - OpsGenie
 - Pushbullet
 - Pushover
 - Rocketchat
 - Slack
 - Teams
 - Telegram
 - Zulip Chat
 - Generic Webhook

Documentation: [Offical docs](https://containrrr.dev/shoutrrr/services/overview/).

To set up notifications for Shoutrrr, head to `Settings > Notifications`.

1. Click **Add new**.
2. Pick Shoutrrr from the list and give it a name.
3. Add your Shoutrrr URL that contains the service and variables, eg: `slack://[botname@]token-a/token-b/token-c`
4. Click the `Test` button to try and send a test notification.
5. Save.

### Telegram

Telegram is a bit more tricky to set up.

1. Click **Add new**.
2. Pick Telegram from the list and give it a name.
3. Choose what events it should trigger on. You can enable all in the same agent or create separate agents for separate events.
4. [Create a bot](https://core.telegram.org/bots#6-botfather) with `BotFather`.
5. Start a chat with your bot, add [@get_id_bot](https://telegram.me/get_id_bot), and issue the /my_id command to retrieve your chat ID.
6. Add your Chat ID, Bot Token, and the Message Thread ID.
7. Optionally set **Telegram API Proxy**: an alternate or reverse-proxied base URL for `api.telegram.org`, only needed if your network blocks the Telegram API.
8. Optionally set **Sender**: a custom name prepended to each notification.
9. Click the `Test` button to try and send a test notification.
10. Save.

### Webhook

Send notifications as HTTP requests to any endpoint, for integrating with your own scripts and services. Not to be confused with Shoutrrr's generic webhook service above; this is a native agent with a structured JSON payload.

1. Click **Add new**.
2. Pick Webhook from the list and give it a name.
3. Choose what events it should trigger on.
4. Add your endpoint URL.
5. Optionally pick an HTTP method (defaults to `POST`) and add custom headers as comma separated `KEY=value` pairs, e.g. `Authorization=Bearer mytoken`.
6. Click the `Test` button to try and send a test notification.
7. Save.

Each request carries an `X-Autobrr-Event` header and a JSON body with the namespaced event name (`release.new`, `action.approved`, `action.rejected`, `action.error`, `irc.disconnected`, `irc.reconnected`, ...), a timestamp, the autobrr version, and event data such as the release, indexer, filter, action and result.

## Per-filter notifications

Notifications can also be configured per filter, in the **Notifications** tab of the filter. Select one of your notification agents, then choose which events should fire for this filter (Push Approved, Push Rejected, Push Error).

Per-filter settings override the agent's global event selection for releases matching that filter; there is no fallback to the global events once custom events are set. Saving the tab with no events selected mutes notifications from this filter entirely.

---

## Proxies

autobrr can use proxies for Indexers (downloads of .torrents, api calls, and their Feeds) and IRC.

## Supported Proxy types

### SOCKS5

To set up a SOCKS5 Proxy, head to `Settings > Proxies`.

1. Click **Add new**.
2. Pick SOCKS5 from the list and give it a name.
3. Add your proxy URL like `socks5://ip:port`.
4. If the proxy requires authentication, fill in both the **User** and **Pass** fields.
5. Click the `Test` button to make a test query (it fetches our docs).
6. Save.

### HTTP(S)

To set up a HTTP Proxy, head to `Settings > Proxies`.

1. Click **Add new**.
2. Pick HTTP from the list and give it a name.
3. Add your proxy URL like `http://ip:port` or `https://ip:port`.
4. If the proxy requires authentication, fill in both the **User** and **Pass** fields.
5. Click the `Test` button to make a test query (it fetches our docs).
6. Save.

## Usage

After you've setup a proxy you need to add it to Indexers and IRC networks. Toggle **Use Proxy** and select the proxy you setup earlier (for indexers: `Settings > Indexers > edit indexer`).

Feeds have no proxy setting of their own; a feed automatically uses the proxy configured on its parent indexer.

---

## Contributing to autobrr

Thanks for taking interest in contribution! We welcome anyone who wants to contribute.

If you have an idea for a bigger feature or a change then we are happy to discuss it before you start working on it.
It is usually a good idea to make sure it aligns with the project and is a good fit.
Open an issue or post in #dev-general on [Discord](https://discord.autobrr.com/).

This document is a guide to help you through the process of contributing to autobrr.

## Become a contributor {/* #become-a-contributor */}

- Code: new features, bug fixes, improvements
- Report bugs
- Documentation: The docs repo can be found here: [github.com/autobrr/autobrr.com](https://github.com/autobrr/autobrr.com)

## Developer guide {/* #developer-guide */}

This guide helps you get started developing autobrr.

## Dependencies {/* #dependencies */}

Make sure you have the following dependencies installed before setting up your developer environment:

- [Git](https://git-scm.com/)
- [Go](https://golang.org/dl/) (see [go.mod](https://github.com/autobrr/autobrr/blob/develop/go.mod#L3) for minimum required version)
- [Node.js](https://nodejs.org) (we usually use the latest Node LTS version - for further information see `@types/node` major version in [package.json](https://github.com/autobrr/autobrr/blob/develop/web/package.json))
- [pnpm](https://pnpm.io/installation)

## How to contribute {/* #how-to-contribute */}

- **Fork and Clone:** [Fork the autobrr repository](https://github.com/autobrr/autobrr/fork) and clone it to start working on your changes.
- **Branching:** Create a new branch for your changes. Use a descriptive name for easy understanding.
  - Checkout a new branch for your fix or feature `git checkout -b fix/filters-issue`
- **Coding:** Ensure your code is well-commented for clarity. With go use `go fmt`
- **Commit Guidelines:** We appreciate the use of [Conventional Commit Guidelines](https://www.conventionalcommits.org/en/v1.0.0/#summary) when writing your commits.
  - Examples: `fix(indexers): Mock improve parsing`, `feat(notifications): add NewService`
  - There is no need for force pushing or rebasing. We squash commits on merge to keep the history clean and manageable.
- **Pull Requests:** Submit a pull request from your Fork with a clear description of your changes. Reference any related issues.
  - Mark it as Draft if it's still in progress.
- **Code Review:** Be open to feedback during the code review process.

## Development environment {/* #development-environment */}

The backend is written in Go and the frontend is written in TypeScript using React.

You need to have the Go toolchain installed and Node.js with `pnpm` as the package manager.

Clone the project and change dir:

```shell
git clone github.com/YOURNAME/autobrr && cd autobrr
```

## Frontend {/* #frontend */}

First install the web dependencies:

```shell
cd web && pnpm install
```

Run the project:

```shell
pnpm dev
```

This should make the frontend available at [http://localhost:3000](http://localhost:3000). It's setup to communicate with the API at [http://localhost:7474](http://localhost:7474).

### Build {/* #build-frontend */}

In order to build binaries of the full application you need to first build the frontend.

To build the frontend, run:

```shell
pnpm --dir web run build
```

## Backend {/* #backend */}

Install Go dependencies:

```shell
go mod tidy
```

Run the project:

```shell
go run cmd/autobrr/main.go
```

This uses the default `config.toml` and runs the API on [http://localhost:7474](http://localhost:7474).

### Build {/* #build-backend */}

To build the backend, run:

```shell
make build/app
```

This will output a binary in `./bin/autobrr`

You can also build the frontend and the backend at once with:

```shell
make build
```

### Build cross-platform binaries {/* #build-cross-platform-binaries */}

You can optionally build it with [GoReleaser](https://goreleaser.com/) which makes it easy to build cross-platform binaries.

Install it with `go install` or check the [docs for alternatives](https://goreleaser.com/install/):

```shell
go install github.com/goreleaser/goreleaser@latest
```

Then to build binaries, run:

```shell
goreleaser build --snapshot --clean
```

## Tests {/* #tests */}

The test suite consists of only backend tests at this point. All tests run per commit with GitHub Actions.

### Run backend tests {/* #run-backend-tests */}

We have a mix of unit and integration tests.

Run all non-integration tests:

```shell
go test -v ./...
```

### Run SQLite and PostgreSQL integration tests {/* #run-sqlite-and-postgresql-integration-tests */}

The integration tests runs against an in memory SQLite database and currently requires Docker for the Postgres tests.

If you have docker setup then run the `test_postgres` container with:

```shell
docker compose up -d test_postgres
```

Then run all tests:

```shell
go test ./... -tags=integration
```

## Build Docker image {/* #build-docker-image */}

To build a Docker image, run:

```shell
make build/docker
```

The image will be tagged as `autobrr:dev`

## Mock indexer {/* #mock-indexer */}

We have a mock indexer you can run locally that features:

- Built in IRC server that can send announces
- Mock indexer for downloads
- RSS feed mock
- Webhook mock for External Filters

See the documentation [here](https://github.com/autobrr/autobrr/blob/develop/test/mockindexer/README.md). Add the `customDefinitions` to the `config.toml` and then run it with:

```shell
go run test/mockindexer/main.go
```

- Restart the backend API for it to load the new mock.yaml definition
- Then add it via Settings -> Indexers -> Add, and select Mock Indexer in the list
- Go to Settings -> IRC and toggle the IRC network `Mock Indexer`
- Add a new Filter or add the indexer to an existing filter
- Open a new tab and navigate to [http://localhost:3999](http://localhost:3999) and put the example announce in the input then hit enter

---

## Frequently Asked Questions

# FAQ

If the docs did not answer your questions then the best place to ask is in our [Discord community](https://discord.autobrr.com/).

## I think I found a bug {/* #i-think-i-found-a-bug */}

If you think you have found a bug then please report it either on [Github Issues](https://github.com/autobrr/autobrr/issues/new?assignees=&labels=bug&projects=&template=bug_report.md&title=) or in our Discord and use the `#bugs` channel.

## I have a feature request {/* #i-have-a-feature-request */}

If you have a feature request then report it on [Github Feature Request](https://github.com/autobrr/autobrr/discussions/new?category=ideas) or in our Discord and use the `#suggestions` channel.

## Nothing happens - I'm not seeing any releases {/* #nothing-happens---im-not-seeing-any-releases */}

Before you ask for help in Discord or other place, then try to forumlate your question so it's easier to help you.

Please clarify what you actually mean.

1. What doesn't happen? Is it filter related? Client related?
2. What did you expect to happen?

There could be multiple reasons. Only filtered releases that gets to the action stage will show up in **Releases**. That means:

- \*arr actions that gets Approved or Rejected.
- Releases sent to a torrent client
- Releases that sent a webhook or ran custom scripts and so on.

:::tip

Go over your setup again and make sure that:

1. You have added some indexer and enabled it.
2. Check `Settings -> IRC` and make sure the network is GREEN. If it's gray it's not enabled.
3. Did you add **a filter**, which is **enabled**, **have at least 1 indexer selected** and any **action** to run on match.
4. Your filter might be too narrow/specific. A common issue is selecting everything in Quality. Deselect everything except resolution.

:::

## Common action rejections {/* #common-action-rejections */}

export const Highlight = ({children, color}) => (

{children}

);

    Rejected: error downloading torrent file for release: Some Release name: All attempts fail: #1: metainfo could not load file contents: /tmp/autobrr-3310314409: bencode: syntax error (offset: 0): unknown value type

This is highly likely caused by you adding an entire URL instead of just the RSS-key. This field only works with an alphanumeric string.

With TorrentLeech as an example, only add the red part when setting up your indexer:

`https://rss.tl.org/`1812u12urr1203j12jeq

In case you are still having troubles with setting up the TorrentLeech indexer,
you can find detailed instructions for the setup process on their wiki:

[https://wiki.torrentleech.org/doku.php/autobrr](https://wiki.torrentleech.org/doku.php/autobrr)

## I have set up an indexer, but it does not connect to the #announce channel. What do I do? {/* #i-have-set-up-an-indexer-but-it-does-not-connect-to-the-announce-channel-what-do-i-do */}

Make sure you have entered the necessary keys in the invite command and that your IRC user has privileges to access to the #announce channel. See [IRC setup](./configuration/irc.mdx).

## Setting a custom save path for Deluge in autobrr does not work. Why? {/* #setting-a-custom-save-path-for-deluge-in-autobrr-does-not-work-why */}

This is a problem with Deluge v1.\* and should not happen in v2.
You can use the label-plugin in Deluge and set a custom save path in that as a workaround. autobrr creates the label if it does not exist, but for this workaround you need to create it yourself first so you can set its save path in Deluge.

## Why did a release not match when it clearly should have? {/* #why-did-a-release-not-match-when-it-clearly-should-have */}

Check your logs. Additionally, enable trace logging by setting `logLevel = "TRACE"` in your `config.toml` (which can usually be found in `~/.config/autobrr/`). The change is picked up automatically without a restart. You can also change the log level on the fly under **Settings > Logs** in the web UI.

## How does autobrr handle multiple matching filters for a release? {/* #how-does-autobrr-handle-multiple-matching-filters-for-a-release */}

When a release is processed, autobrr checks all the filters in order of priority (higher number = higher priority). If a filter matches the release, autobrr executes all the actions defined in that filter and then stops processing further filters for that release. The exception here is \*arr actions. If e.g., Radarr or Sonarr rejects a release, the next filter in line will be processed.

## My autobrr instance cannot reach Deluge running in Docker {/* #my-autobrr-instance-cannot-reach-deluge-running-in-docker */}

If autobrr isn't reaching Deluge when running Docker you can try this:

- `Host` should be the deluge container you're trying to reach, it will probably just be `deluge`.
  Make sure that your docker containers are on the same network, so they can reach each other. If you're using a single compose file, it should be by default.
- `Port` should be the daemon port, not the webui port. Find the correct one by logging into Deluge webui, and checking in Preferences or under Connection Manager (default: 58846).
- `Authentication` is required for deluge daemon, not the webui.
  It can be found at `/docker/appdata/deluge/auth`, the default one looks like `localclient:password:10`.
  You can add your own if you wish. Like `username:password:powerlevel`.
- Enabling `Allow Remote Connections` in Deluge might be needed depending on your setup.

## I forgot my password {/* #forgot-password */}

If you forget your password, you can change it via the command line.

```bash
autobrrctl --config /home/username/.config/autobrr change-password <USERNAME>
```

## I want to change my username {/* #change-username */}

If you want to change your username, you can do so via the [web UI](./usage/account.mdx).
If you don't have access to the web UI, you need to change it directly in the database.
Use the command line or an sqlite editor.

### CLI {/* #cli */}

You need the `sqlite3` package for this.

- If you are using our docker container then you can exec in and run `apk add sqlite3`.
- Ubuntu: `sudo apt install sqlite3`
- On other linux based systems use the package manager to install the package

`sqlite3 autobrr.db "UPDATE users SET username = 'newuser';"`

### GUI {/* #gui */}

SQLitebrowser is a simple cross-platform SQLite gui/browser. Download from [official site](https://sqlitebrowser.org/dl/).

Open the db file `autobrr.db` and run the following command:

`UPDATE users SET username = 'newuser';`

Or use the gui to click edit on the `username` column of the `users` table.

## How can I use my freeleech tokens from RED? {/* #redacted-freeleech-tokens */}

This is something a lot of users are asking for.

Golden Rule 5.3 on RED:

> Do not autosnatch freeleech torrents.
> The automatic snatching of freeleech torrents using any method involving little or no user-input (e.g., API-based scripts, log or site scraping, etc.) is prohibited.

We have asked RED staff, and they have confirmed that automating the use of freeleech tokens falls under this rule.

While the possibility to do it exists, its not something we will encourage users to do. Always make sure you respect the rules of any tracker that you are a part of.

---

## Actions

:::note
Make sure you've set up a [download client](../configuration/download-clients/dedicated) before continuing further.
:::

A configured action is what autobrr will push a successful match to. Each filter supports multiple actions, just in case you need to send to multiple clients or run custom commands as well. Actions are configured in the Action tab inside your filter.

The most common setup is sending straight to a download client, with the category, save path and limits you set on the action:

Whether you're adding, updating, or removing actions in a filter, remember to **save** the filter afterwards to ensure your changes take effect.

### Macros {/* #macros */}

Many of the action fields have support for [macros](../filters/macros.mdx), which allow you to enhance your workflow significantly by providing custom logic/data processing to the input data provided by autobrr.

The [macro section](../filters/macros.mdx) has been moved to its own page.

## Supported actions {/* #supported-actions */}

- qBittorrent
- Deluge (v1+ and v2)
- rTorrent
- Transmission
- Porla
- aria2
- SABnzbd (Usenet)
- NZBGet (Usenet)
- Radarr
- Sonarr
- Lidarr
- Readarr
- Whisparr
- Save to watch folder
- Exec - Run custom commands
- Webhook - Post a payload to some http url
- Test (logs result if matched. Does not download torrent files)

### qBittorrent {/* #qbittorrent */}

Send to one or multiple local or remote instances of qBittorrent.

#### Available options: {/* #qbittorrent-available-options */}

- **Save path**: *optional*  
- **Download path**: *optional*  
  A separate path for incomplete downloads. If you use categories with Automatic Torrent Management, qBittorrent controls this instead.
- **Category**: *optional*  
- **Tags**: *optional*

:::tip
If a category is set, then qBittorrent will control the save path. Override the save location by setting a save path if needed.
:::

#### Rules: {/* #qbittorrent-rules */}

- **Limit download and upload speed**: *optional*  
  Takes any integer as a number. Given in `KiB/s`.
- **Ratio limit**: *optional*  
  Takes an integer or decimal number in increments of `0.25`, with `.` as decimal separator, e.g. `2.0`.  
  The downloaded torrent will be stopped when the ratio limit is reached.
- **Seed time limit**: *optional*  
  Takes any integer as a number. Given in minutes.
  The downloaded torrent will be stopped when the seed time limit is reached.
- **Add paused**: *default false*
- **Content layout**: *optional*  
  Tells qBittorrent if it should:  
    - Keep the original torrent content layout,  
    - Create a subfolder for the downloaded torrent,  
    - Refrain from creating a subfolder.
- **Ignore client rules**: *default false*  
  Download the torrent even though the maximum active downloads configured in the client settings have been reached.
- **Skip hash check**: *default false*
- **Download first and last pieces first**: *default false*
- **Priority**: *optional*  
  Choose between:
  - Top of queue
  - Bottom of queue
  - Disabled

:::warning[Heads up!]
When using the Priority feature, Torrent Queueing will be automatically enabled in qBit if it is disabled. Ensure you set your preferred limits for Torrent Queueing.
:::

#### Announce: {/* #qbittorrent-announce */}

Built-in re-announce makes sure the torrent works with initially broken trackers. When you race, the .torrent often reaches the client before the tracker has registered it; autobrr keeps re-announcing until the tracker responds:

It is enabled by default and can be tuned per action:

- **Disable reannounce**: *default false*  
  Turn off the built-in re-announce for this action.
- **Reannounce interval**: *optional*  
  Seconds between attempts. `7` is the default and recommended.
- **Max attempts**: *optional*  
  How many times to retry before giving up. Default `50`.
- **Delete stalled**: *default false*  
  Remove the torrent from the client if it is still not working after the maximum attempts.

:::info
Re-announce is skipped when the torrent is added with **Add paused** enabled.
:::

### Deluge {/* #deluge */}

Supports both v1+ and v2+ clients.

Send to one or multiple local or remote instances of Deluge.

#### Available options: {/* #deluge-available-options */}

- **Save path**: *optional*  
- **Label**: *optional* (created automatically if it does not exist; requires the Label plugin to be enabled in Deluge, otherwise the label is skipped)
- **Add as paused**: *default false*
- **Skip hash check (v2 only)**: *default false*

#### Rules: {/* #deluge-rules */}

- **Limit download and upload speed**: *optional*  
  Takes any integer as a number. Given in `KiB/s`.

### rTorrent {/* #rtorrent */}

Send to one or multiple local or remote instances of rTorrent.

#### Available options: {/* #rtorrent-available-options */}

- **Save path**: *optional*
- **Label**: *optional*
- **Add paused**: *default false*  
  Adds the torrent in a stopped state.
- **Do not add torrent name to path**: *default No*  
  When set to Yes, the save path is used as the base directory, so no subfolder named after the torrent is created.

### Transmission {/* #transmission */}

Send to one or multiple local or remote instances of Transmission.

#### Available options: {/* #transmission-available-options */}

- **Save Path**: *optional*
- **Torrent Label(s)**: *optional*  
  Takes a comma separated list to apply multiple labels, e.g. `label1,label2`.
- **Add as Paused**: *default false*

#### Limits: {/* #transmission-limits */}

- **Limit download and upload speed**: *optional*  
  Takes any integer as a number. Given in `KiB/s`.
- **Ratio limit**: *optional*  
  Seeding stops when the ratio is reached.
- **Seed time limit**: *optional*  
  Given in minutes. Set as Transmission's idle seed limit, meaning minutes of idle seeding rather than total seed time.

#### Announce: {/* #transmission-announce */}

Works like the [qBittorrent re-announce](#qbittorrent-announce): enabled by default, with the same **Disable reannounce**, **Reannounce interval** (default `7` seconds), **Max attempts** (default `50`) and **Delete stalled** options.

:::info
Re-announce only runs when the torrent is added unpaused, and is skipped for magnet links.
:::

### Porla {/* #porla */}

Send to one or multiple local or remote instances of Porla.

#### Available options: {/* #porla-available-options */}

- **Save Path**: *optional*
- **Preset**: *A case-sensitive preset name as configured in Porla.*

#### Rules: {/* #porla-rules */}

- **Limit download and upload speed**: *optional*  
  Takes any integer as a number. Given in `KiB/s`.

### aria2 {/* #aria2 */}

Send to one or multiple local or remote instances of aria2.

#### Available options: {/* #aria2-available-options */}

- **Save Path**: *optional*
- **Add Paused**: *default false*

#### Limits: {/* #aria2-limits */}

- **Limit download and upload speed**: *optional*  
  Takes any integer as a number. Given in `KiB/s`.
- **Ratio limit**: *optional*  
  Seeding stops when the ratio is reached.
- **Seed time limit**: *optional*  
  Given in minutes.

### SABnzbd / NZBGet {/* #sabnzbd--nzbget */}

Send NZBs to one or multiple local or remote instances of SABnzbd or NZBGet.

These actions only work for usenet (NZB) releases, for example from [Newznab or NZB-type RSS feeds](../configuration/feeds.mdx). Torrent releases cannot be sent to them.

#### Available options: {/* #sabnzbd-nzbget-available-options */}

- **Category**: *optional* (must already exist in the client)

### Radarr, Sonarr, Lidarr, Readarr and Whisparr {/* #radarr-sonarr-lidarr-readarr-and-whisparr */}

Autobrr supports the ability to push directly to the *arr suite of services. Both local and remote instances.

*arr actions are special: the *arr decides whether it actually wants the release. If it approves, it grabs the release and autobrr stops there. If it rejects (say the show isn't monitored, or the release isn't an upgrade), autobrr moves on and tries the next filter that matches the release, without pushing to the same client again:

Select the type, and then the client. Read more about setup in [download clients setup](../configuration/download-clients/dedicated).

Pushes to Radarr and Sonarr include indexer flags such as freeleech, so any indexer flag preferences you have configured on the arr side are applied.

:::tip
It could be useful to do some basic filtering.

See [examples here](/filters/examples).
:::

### Test {/* #test */}

A simple action which will not download anything, but is useful for **filter testing**.

### Watch Dir {/* #watch-dir */}

For torrent clients not yet supported, the watch dir is the next best option.

By default, if you only specify the folder path (e.g., `/home/USER/watch/`), it will use the temporary file format, such as `autobrr-000.torrent`.

:::tip[Dynamic Naming]

Watch Dir can utilize additional variables to dynamically build the file name. If you want to change the naming convention and, for example, include the indexer name and the torrent name, you can use the following format:

    `/home/user/torrent/torrent-backup/{{.Indexer}}-{{.TorrentName}}.torrent`

If the indexer is called `MockIndexer` and the release is `Some.Release.2022.1080p.BluRay.x264.DTS-GROUP`, the generated file name will be `MockIndexer-Some.Release.2022.1080p.BluRay.x264.DTS-GROUP.torrent`.
:::

:::caution
The watch folder action does not support magnet links and will error for magnet-only releases. Use a supported torrent client action for those indexers.
:::

### Custom Commands / Exec {/* #custom-commands--exec */}

For custom commands, it's best to specify the full path to the binary or program you want to run. This ensures that the command can be executed correctly, regardless of the user's environment. You can also include your own static variables to make the command more dynamic and flexible.

:::tip
For example, you could use:

- `race-{{.Indexer}}/{{.Resolution}}` as a tag or category
- `/Movies/{{.Resolution}}` as a save path

:::

### Webhook {/* #webhook */}

Post a payload to an HTTP endpoint when the filter matches. Useful for integrating with your own scripts and services.

- **Endpoint**: the URL to send the request to, e.g. `http://127.0.0.1:5000/api/upgrade`
- **Payload (json)**: the JSON body to send, with full [macro](../filters/macros.mdx) support, e.g. `{ "name": "{{ .TorrentName }}" }`

The request is always an HTTP `POST` with `Content-Type: application/json`.

:::tip
If you want the result of the request to decide whether the filter matches, use an [external filter webhook](./external.mdx) instead. The Webhook action fires after the filter has already matched.
:::

### FTP / SFTP {/* #ftp--sftp */}

Although autobrr does not have a native FTP upload action, you can achieve this functionality by using an Exec action and a tool like `scp`.

:::tip
Use the following command and arguments to set up an Exec action for FTP/SFTP uploads:

- Command: `scp`
- Args: `{{ .TorrentPathName }} <username>@<hostname>:<destination path>`

:::

![FTP/SFTP](/img/SCP.png "Exec action for FTP/SFTP upload")

---

## Advanced


## Releases {/* #releases */}

:::info

Full regex support (Golang flavour, check https://regex101.com). These fields hardcode the mode `(?i)` **case-insensitive**

:::

| Field                  | Description                                                                           | Examples                                            | Availability |
| ---------------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------- | ------------ |
| \* **Match releases**  | Comma separated list of release names to match.                                       | e.g. `*Movie*remux*, That Other movie, *that?game*` | Always       |
| \* **Except releases** | Comma separated list of release names to ignore (takes priority over Match releases). | e.g. `Bad?Movie, *bad*`                             | Always       |

:::caution[Substring matching]
Unlike most other filter fields, in non-regex mode each comma separated term here is matched as a case-insensitive **substring** of the release name. Wildcards still work but are not required for partial matches, and exact-only matching is not possible without regex. Be careful with short Except terms: `web` also rejects every `WEB-DL` release.
:::

## Release groups {/* #release-groups */}

| Field                     | Description                                                                            | Examples                        | Availability |
| ------------------------- | -------------------------------------------------------------------------------------- | ------------------------------- | ------------ |
| **Match release groups**  | Comma separated list of release groups to match.                                       | e.g. `GROUP1, OTHERGROUP`       | Always       |
| **Except release groups** | Comma separated list of release groups to ignore (takes priority over Match releases). | e.g. `BADGROUP1, OTHERBADGROUP` | Always       |

## Categories {/* #categories */}

Not all announces category, check [this list](./categories.mdx) for indexer specifics.

| Field                 | Description                                                                        | Examples                  | Availability                          |
| --------------------- | ---------------------------------------------------------------------------------- | ------------------------- | ------------------------------------- |
| **Match categories**  | Comma separated list of categories to match.                                       | e.g. `tv,tv/1080p`        | [Depends on Indexer](./categories.mdx) |
| **Except categories** | Comma separated list of categories to ignore (takes priority over Match releases). | e.g. `tv/anime,tv/sports` | [Depends on Indexer](./categories.mdx) |

## Tags {/* #tags */}

| Field            | Description                                                                                                 | Examples              | Availability       |
| ---------------- | ------------------------------------------------------------------------------------------------------------ | --------------------- | ------------------ |
| **Match tags**   | Comma separated list of tags to match.                                                                       | e.g. `action,romance` | Depends on Indexer |
| **Match logic**  | How multiple Match tags combine: `ANY` matches if at least one tag is present, `ALL` requires every tag.     | `ANY` (default)       | Always             |
| **Except tags**  | Comma separated list of tags to ignore (takes priority over Match releases).                                 | e.g. `foreign`        | Depends on Indexer |
| **Except logic** | How multiple Except tags combine: `ANY` rejects if at least one tag is present, `ALL` requires every tag.    | `ANY` (default)       | Always             |

## Uploaders {/* #uploaders */}

| Field                | Description                                                                       | Examples                       | Availability       |
| -------------------- | --------------------------------------------------------------------------------- | ------------------------------ | ------------------ |
| **Match uploaders**  | Comma separated list of uploaders to match.                                       | e.g. `uploader1,otheruploader` | Depends on Indexer |
| **Except uploaders** | Comma separated list of uploaders to ignore (takes priority over Match releases). | e.g. `anonymous,slow_uploader` | Depends on Indexer |

:::info
On Redacted and Orpheus, announces do not include the uploader. autobrr fetches it from the tracker API instead and re-checks the filter, so uploader filtering still works there. This requires the indexer's API key to be configured in autobrr.
:::

## Languages {/* #languages */}

Only works when the indexer announces language information.

| Field               | Description                                                                       | Examples          | Availability       |
| ------------------- | ---------------------------------------------------------------------------------- | ----------------- | ------------------ |
| **Match language**  | Match releases containing any of the selected languages.                          | e.g. `MULTi`      | Depends on Indexer |
| **Except language** | Ignore releases containing any of the selected languages (takes priority).        | e.g. `FRENCH`     | Depends on Indexer |

## Origins {/* #origins */}

Only works when the indexer announces the release origin.

| Field              | Description                                                                       | Examples      | Availability       |
| ------------------ | ---------------------------------------------------------------------------------- | ------------- | ------------------ |
| **Match origins**  | Match releases with any of the selected origins: `P2P`, `Internal`, `SCENE`, `O-SCENE`. | e.g. `Internal` | Depends on Indexer |
| **Except origins** | Ignore releases with any of the selected origins (takes priority).                | e.g. `P2P`    | Depends on Indexer |

## Freeleech {/* #freeleech */}

Not supported by all indexers. Check [this list](./freeleech.mdx) for indexer specifics.

| Field                 | Description                                            | Examples           | Availability                                                 |
| --------------------- | ------------------------------------------------------ | ------------------ | ------------------------------------------------------------ |
| **Freeleech**         | Should this filter match only Freeleech releases?      |                    | [Depends on Indexer](./freeleech.mdx)                         |
| **Freeleech Percent** | Allowed Freeleech Percentage for this filter to match. | e.g. `50%,75-100%` | [Depends on Indexer, might not use percent.](./freeleech.mdx) |

## RSS/Torznab/Newznab-specific {/* #feed-specific */}

These options only work for [Feeds](../configuration/feeds.mdx) such as RSS, Torznab and Newznab. They have no effect on IRC announces.

| Field                  | Description                                                                                | Examples                          | Availability            |
| ---------------------- | ------------------------------------------------------------------------------------------ | --------------------------------- | ----------------------- |
| **Match description**  | Comma separated list matched against the feed item description.                           | e.g. `*some?movie*,*some?show*s01*` | Feeds only              |
| **Except description** | Comma separated list to ignore in the description (takes priority over Match description). | e.g. `*hardcoded*subs*`           | Feeds only              |
| **Use regex**          | Toggle regex mode for the two description fields above.                                    |                                   | Feeds only              |
| **Min / Max seeders**  | Only match when the number of seeders is within the given bounds.                          | e.g. `1` / `100`                  | Torznab feeds only      |
| **Min / Max leechers** | Only match when the number of leechers is within the given bounds.                         | e.g. `0` / `50`                   | Torznab feeds only      |

## Raw Release Tags {/* #raw-release-tags */}

For advanced users. These fields match against the raw, unparsed `releaseTags` string from the announce, like `FLAC / Lossless / Log / Cue` or `x264 / 1080p / MKV`, before autobrr parses it into separate fields.

| Field                   | Description                                                                          | Examples             | Availability       |
| ----------------------- | -------------------------------------------------------------------------------------- | -------------------- | ------------------ |
| **Match release tags**  | Comma separated list to match, wildcards supported.                                  | e.g. `*mkv*,*foreign*` | Depends on Indexer |
| **Except release tags** | Comma separated list to ignore (takes priority over Match release tags).             | e.g. `*log?100*`     | Depends on Indexer |
| **Use regex**           | Toggle regex mode for the two release tag fields above.                              |                      | Depends on Indexer |

---

## Category Examples

This list was created with help from users like you. If you have others, please add them yourself or reach out on discord and we can add more. See how to export categories [here](#how-to-export-categories-from-autobrrdb).

## Categories

As a rule of thumb, simple filtering rules such as `*TV*,*Episode*` or `*Movie*` will sufice for most users needs
### Aither

### AlphaRatio

### Animebytes

### AnimeWorld

### BeyondHD

### BitHDTV

### BroadcasTheNet

### BTFiles

### CathodeRayTube

### DarkPeers

### DigitalCore

### F1Carreras

### Filelist

### GazelleGames

### HDBits

### HDSpace

### HDTorrents

### Huno

### ImmortalSeed

### IPTorrents

### Lost

### Milkie

### MorethanTV

### MyAnonamouse

### Nebulance

### Norbits

### Nyaa

### PassThePopcorn

### RED

### RevolutionTT

### SpeedApp

### Superbits

### SeedPool

### TorrentDay

### Torrentleech

### TorrentSyndikat

### xSpeeds

## How to export categories from autobrr.db

You can export categories from your autobrr.db like this:

```bash
sqlite3 /path/to/autobrr.db "SELECT DISTINCT indexer, category FROM "release" ORDER BY indexer, category;" ".exit" > dump.txt
```

You can add them to this page by opening a [pull request](https://github.com/autobrr/autobrr.com/pulls) or by providing them to us on [Discord](https://discord.autobrr.com/).

---

## Cross-seed with qui

# Cross-seed with qui {/* #cross-seed-with-qui */}

[qui](https://getqui.com) is our multi-instance qBittorrent WebUI with built-in cross-seed support. It integrates with autobrr through webhook endpoints, enabling real-time cross-seed detection when autobrr sees a new announce.

Unlike the [cross-seed](../3rd-party-tools/cross-seed.mdx) third party setup, this is a first party integration: no extra daemon, config file or torznab endpoints are needed. If you run qBittorrent and qui, all you need is a filter in autobrr.

## How it works {/* #how-it-works */}

1. autobrr sees a new release from a tracker
2. autobrr sends the torrent name and indexer identifier to qui's `/api/cross-seed/webhook/check` endpoint via an external filter
3. qui searches your qBittorrent instances for matching content and responds with:
   - `200 OK`: a matching torrent is complete and ready to cross-seed
   - `202 Accepted`: a matching torrent exists but is still downloading; autobrr retries later
   - `404 Not Found`: no matching torrent exists
4. On `200 OK`, an autobrr action sends the torrent file to qui's `/api/cross-seed/apply` endpoint, which adds it to qBittorrent

Cross-seeded torrents are added paused with `skip_checking=true`. qui polls the torrent state and auto-resumes if progress meets the size tolerance threshold. If progress is too low, the torrent remains paused for manual review.

## Setup {/* #setup */}

### 1. Create an API key in qui {/* #qui-api-key */}

In qui, go to **Settings → API Keys**, click **Create API Key**, name it (e.g. `autobrr webhook`) and copy the generated key. We will refer to it as `YOUR_QUI_API_KEY` below.

### 2. Create the filter {/* #create-filter */}

:::info
Create a new filter dedicated to qui. Select all the indexers you want to cross-seed from, preferably all of them.
:::

Create a filter named e.g. `qui cross-seed` and set a really high `priority` to make sure it runs before your other filters.

### 3. Add the external webhook {/* #external-webhook */}

Go to the **External** tab of the filter and add a new external filter:

| Field                     | Value                                                |
| ------------------------- | ---------------------------------------------------- |
| Type                      | `Webhook`                                            |
| Name                      | `qui`                                                |
| On Error                  | `Reject`                                             |
| Endpoint                  | `http://localhost:7476/api/cross-seed/webhook/check` |
| HTTP Method               | `POST`                                               |
| HTTP Request Headers      | `X-API-Key=YOUR_QUI_API_KEY`                         |
| Expected HTTP Status Code | `200`                                                |

Data (JSON):

```json
{
  "torrentName": {{ toRawJson .TorrentName }},
  "instanceIds": [1],
  "indexer": {{ toRawJson .Indexer }}
}
```

To search all your qBittorrent instances, omit `instanceIds`:

```json
{
  "torrentName": {{ toRawJson .TorrentName }},
  "indexer": {{ toRawJson .Indexer }}
}
```

Field descriptions:

- `torrentName` (required): the release name as announced
- `instanceIds` (optional): qBittorrent instance IDs to scan; omit to search all instances
- `indexer` (optional): autobrr indexer identifier (e.g. `hdb`); required for qui's HDBits-specific missing-collection fallback
- `findIndividualEpisodes` (optional): override qui's global episode matching setting

:::tip[Docker Compose]
If autobrr and qui are both containers, `localhost` inside autobrr is the autobrr container, not qui. Use the qui container hostname instead (often the Compose service name), for example `http://qui:7476/api/cross-seed/webhook/check`.
:::

### 4. Configure retry handling {/* #retry-handling */}

qui answers `202 Accepted` when a match exists but is still downloading. Use the **Retry** block of the external filter to handle this:

- **Retry HTTP status code(s):** `202`
- **Maximum retry attempts:** `10`
- **Retry delay in seconds:** `4`

### 5. Add the apply action {/* #apply-action */}

:::caution
The external webhook only answers "is this ready to cross-seed?"; it does not add anything to qBittorrent. You must also add this action, otherwise nothing gets added.
:::

Go to the **Actions** tab of the filter and add a new action:

| Field       | Value                                                                |
| ----------- | -------------------------------------------------------------------- |
| Action Type | `Webhook`                                                            |
| Name        | `qui cross-seed`                                                     |
| Endpoint    | `http://localhost:7476/api/cross-seed/apply?apikey=YOUR_QUI_API_KEY` |

Payload (JSON):

```json
{
  "torrentData": "{{ .TorrentDataRawBytes | toString | b64enc }}",
  "instanceIds": [1],
  "indexer": {{ toRawJson .Indexer }}
}
```

Field descriptions:

- `torrentData` (required): base64-encoded torrent file bytes
- `instanceIds` (optional): target instances; omit to apply to any matching instance
- `indexer` (optional): autobrr indexer identifier (e.g. `hdb`); when qui's "Use indexer name as category" mode is enabled, qui uses this as the category
- `tags` (optional): override webhook tags from qui's settings
- `category` (optional): override category; takes precedence over `indexer`
- `startPaused` (optional): override whether torrents are added paused
- `skipIfExists` (optional): skip adding if the torrent already exists
- `findIndividualEpisodes` (optional): override qui's global episode matching setting

Finally, make sure the filter is enabled and you're all set.

## Troubleshooting {/* #troubleshooting */}

autobrr shows the filter accepted the release, but nothing shows up in qBittorrent:

1. **Confirm you added the `/apply` action.** The external webhook (`/check`) does not add torrents.
2. **Fix Docker networking.** `http://localhost:7476/...` only works if autobrr can reach qui on its own `localhost`. In Docker Compose, use the qui service hostname, e.g. `http://qui:7476/api/cross-seed/apply?apikey=...`.
3. **Double-check auth.** `/check` uses the header `X-API-Key=...`, while `/apply` uses the query string `?apikey=...`.
4. **Verify qui can talk to qBittorrent.** In the qui UI: **Settings → Instances → Test Connection**.
5. **Check paused torrents.** Cross-seeds are often added paused; look in qBittorrent's paused list and any cross-seed tag/category you configured.

For anything beyond this, see qui's [cross-seed troubleshooting](https://getqui.com/docs/features/cross-seed/troubleshooting) docs.

## Going further {/* #going-further */}

- **Webhook source filters:** by default qui scans all torrents on your instances when looking for matches. You can include/exclude categories and tags in the qui UI under **Cross-Seed → Auto → Webhook / autobrr**.
- **Season packs:** qui has a dedicated season pack flow with separate endpoints (`/api/cross-seed/season-pack/check` and `/api/cross-seed/season-pack/apply`) that links already downloaded episodes into an announced season pack. It requires a separate autobrr filter; see qui's [season packs](https://getqui.com/docs/features/cross-seed/season-packs) docs for full setup instructions.
- Full qui documentation: [getqui.com/docs/features/cross-seed/autobrr](https://getqui.com/docs/features/cross-seed/autobrr)

---

## Filter Examples

# Examples

Here are some example filters that can be useful.

## TV - Sonarr {/* #tv---sonarr */}

When using autobrr with Sonarr these are some good recommendation filters to start off.

It's advisable to setup your Sonarr properly with the help of [Trash-guides](https://trash-guides.info) and then just do some light filtering of releases to not push unwanted releases to Sonarr.

Don't forget to add a [Sonarr action](../filters/actions.mdx#radarr-sonarr-lidarr-readarr-and-whisparr)!

:::caution[Important]
Not all indexers announce video **container** like `mkv` or `mp4`. It's best to leave this off.
:::

### HD WEB (720p, 1080p) {/* #hd-web-720p-1080p */}

Set this to match your quality settings in Sonarr

| Field            | Values                                |
| ---------------- | ------------------------------------- |
| Resolution       | [720p, 1080p]                         |
| Sources          | [WEB, WEB-DL, WEBRip]                 |
| Match Categories | [Depends on Indexer](./categories.mdx) |

### 4k (2160p) {/* #4k-2160p */}

Set this to match your quality settings in Sonarr

| Field            | Values                                |
| ---------------- | ------------------------------------- |
| Resolution       | [2160p]                               |
| Sources          | [WEB, WEB-DL, WEBRip]                 |
| Match Categories | [Depends on Indexer](./categories.mdx) |

### HDR and DV {/* #hdr-and-dv */}

Leave blank to match either and let your arr decide, or do the following to include or exclude HDR formats:

If you **WANT ONLY HDR** formats

| Field     | Values     |
| --------- | ---------- |
| Match HDR | Select all |

If you **DON'T WANT ANY HDR** formats

| Field      | Values     |
| ---------- | ---------- |
| Except HDR | Select all |

:::caution
Selecting only `HDR` and `DV` misses dual-format releases like `DV HDR10`, which only match the combined options (`DV HDR`, `DV HDR10`, `DV HDR10+`). Select all is the safe choice; narrow it down only if you know which formats your indexer announces.
:::

### Only season packs {/* #only-season-packs */}

If you only want to match season packs:

| Field    | Values |
| -------- | ------ |
| Seasons  | 1-99   |
| Episodes | 0      |

### Only episodes, skip season packs {/* #only-episodes-skip-season-packs */}

If you only want to match episodes and no season packs:

| Field    | Values |
| -------- | ------ |
| Seasons  | 1-99   |
| Episodes | 1-99   |

## Movies - Radarr {/* #movies---radarr */}

When using autobrr with Radarr these are some good recommendation filters to start off.

It's advisable to setup your Radarr properly with the help of [Trash-guides](https://trash-guides.info) and then just do some light filtering of releases to not push unwanted releases to Radarr.

Don't forget to add a [Radarr action](./actions.mdx#radarr-sonarr-lidarr-readarr-and-whisparr)!

:::caution[Important]
Not all indexers announce video **container** like `mkv` or `mp4`. It's best to leave this off.
:::

### HD (720p, 1080p) {/* #hd-720p-1080p */}

Set this to match your quality settings in Radarr

| Field            | Values                                |
| ---------------- | ------------------------------------- |
| Resolution       | [720p, 1080p]                         |
| Sources          | [WEB, WEB-DL, WEBRip, BluRay]         |
| Match Categories | [Depends on Indexer](./categories.mdx) |

### 4k (2160p) {/* #4k-2160p-1 */}

Set this to match your quality settings in Radarr

| Field            | Values                                    |
| ---------------- | ----------------------------------------- |
| Resolution       | [2160p]                                   |
| Sources          | [WEB, WEB-DL, WEBRip, BluRay, UHD.Bluray] |
| Match Categories | [Depends on Indexer](./categories.mdx)     |

### HDR and DV {/* #hdr-and-dv-1 */}

Leave blank to match either and let your arr decide, or do the following to include or exclude HDR formats:

If you **WANT ONLY** HDR formats

| Field     | Values     |
| --------- | ---------- |
| Match HDR | Select all |

If you **DON'T WANT ANY HDR** formats

| Field      | Values     |
| ---------- | ---------- |
| Except HDR | Select all |

:::caution
Selecting only `HDR` and `DV` misses dual-format releases like `DV HDR10`, which only match the combined options (`DV HDR`, `DV HDR10`, `DV HDR10+`). Select all is the safe choice; narrow it down only if you know which formats your indexer announces.
:::

## Matching specific titles {/* #matching-specific-titles */}

The **Movies / Shows** field on the [TV & Movies](./tv-movies.mdx) tab matches against the parsed title of the release, and supports the usual wildcards: `*` for zero or more characters, `?` for exactly one. Matching is case-insensitive and must cover the whole title, so add `*` when you only know part of it.

| Pattern      | Matches                                        | Doesn't match             |
| ------------ | ---------------------------------------------- | ------------------------- |
| `The?Batman` | `The Batman`, `The.Batman`                     | `The Batmans`, `TheBatman` |
| `Dune*`      | `Dune`, `Dune Part Two`                        | `The Dune Chronicles`     |
| `*office*`   | `The Office`, `Office Space`                   |                           |
| `Severance`  | `Severance` (exact title only)                 | `Severance US`            |

:::tip
Prefixes match more than you might expect: `Dune*` also matches a title like `Dunes`. When two titles collide, add the year or a separator, e.g. `Dune?Part*`.
:::

## Sports {/* #sports */}

Sports releases parse differently from movies and TV. The league or competition becomes the **title**, while the round, event and session end up in the **sub-title**, and there is no filter field for the sub-title:

This means a `Shows` value of `Formula 1` matches every F1 release: practice, qualifying and race alike. To narrow down to specific sessions, use **Match releases** on the [Advanced](./advanced.mdx#releases) tab, which matches against the whole release name. It matches substrings even without wildcards, and a comma-separated list works as OR:

| Field          | Values                                                        |
| -------------- | ------------------------------------------------------------- |
| Shows          | `Formula 1`                                                    |
| Resolutions    | [1080p]                                                        |
| Match releases | `Formula*1*Race*1080p*, Formula*1*Qualifying*1080p*`           |

This would match `Formula.1.2023.Round.01.BahrainGP.Race.F1.Live.1080p.SS` and the qualifying equivalent, but skip practice sessions. The same pattern works for other sports:

| Sport    | Match releases                              |
| -------- | ------------------------------------------- |
| UFC      | `UFC*PPV*1080p*, UFC*Prelims*1080p*`        |
| Football | `*Premier*League*1080p*`                    |
| MotoGP   | `MotoGP*Race*1080p*`                        |

## Build buffer {/* #build-buffer */}

If you are in need of buffer this is an example that will work will on general indexers with freeleech/bonus systems.

Check your indexer or our [list of indexers supporting freeleech](./freeleech.mdx) filtering for specifics.

| Field     | Values        |
| --------- | ------------- |
| Freeleech | True / active |

And to not flood your torrent client you can use either `Max downloads Per` and set a limit on how many can be downloaded in a time period.

Or better, set the `max active downloads` rule for qBittorrent or Deluge.

This can be set in `Settings -> Clients`, click edit on your client, or create a new identical client with limits.

1. Toggle `Rules`
2. Set `Max active downloads` to 2.

This setting will make the filter check qBittorrent before adding a torrent. If the `Max active downloads` is reached, then it will not add the torrent.
This should not be confused with qBittorrent's BUILT IN setting with the same name. That will add torrents as paused and start only after the limit is below. This will hurt your ratio BAD.

Here's a small chart of recommended `Max active downloads` depending on server type, connection and disks. Try them out and increase the number until you hit negative ratios.

| Type      | Connection | Disks    | Value |
| --------- | ---------- | -------- | ----- |
| Dedicated | 1Gbit      | HDD      | 2     |
| Dedicated | 1Gbit      | SSD/NVME | 2-3   |
| Dedicated | 2Gbit      | HDD      | 2-3   |
| Dedicated | 10Gbit     | HDD      | 2-3   |
| Dedicated | 10Gbit     | SSD/NVME | 4-5+  |
| Shared    | 1Gbit      | HDD      | 1     |
| Shared    | "20Gbit+"  | HDD      | 2-3   |
| Shared    | "20Gbit+"  | SSD/NVME | 2-3   |

And if you have traffic limits, then `max downloads per` is there to help you limit it.

### Other tips {/* #other-tips */}

It's generally a good idea to check the latest torrents and the browse pages to try and look for patterns of what get snatches.

Some indexers and content types the current year releases do get a lot of snatches. If there's internal groups it's highly likely they do very well also.

## Convert autodl-irssi filters {/* #convert-autodl-irssi-filters */}

---

## External


With external filters you can run `scripts` and `webhooks` to do your own custom filtering. If **Expected exit status** matches it will continue. If not it stops there.

Many of the fields have support for [macros](./macros.mdx), which allow you to enhance your workflow significantly by providing custom logic/data processing to the input data provided by autobrr.

We have a separate repo for community scripts created by our users. https://github.com/autobrr/community-scripts

### Script

Run external script that does something. Use `exit codes` correctly, like `exit 0` for no issues. In Linux, non-zero exit codes are considered not-ok/error etc.

External filters run after the filter's own checks have passed, so your script only sees releases that already matched:

See [stop if disk is full](../usage/tips.mdx#stop-if-disk-is-full) for a good example of what it can do.

| Field                    | Description           | Examples                                                       |
| ------------------------ | --------------------- | -------------------------------------------------------------- |
| **Command**              | Command, full path    | e.g. `/usr/bin/myprogram`                                      |
| **Arguments**            | Arguments.            | e.g. `--name {{ .TorrentName }} --file {{ .TorrentPathName }}` |
| **Expected exit status** | Expected exit status. | e.g. `0`                                                       |

### Webhook

Send a payload to some custom API and do more processing. Use status codes to trigger different behaviours.

A real-world example is [cross-seeding with qui](./cross-seed-qui.mdx), where the API's status code decides between cross-seeding now, retrying later, or rejecting:

| Field                         | Description                                                                  | Examples                                  |
| ----------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------- |
| **Endpoint**                  | URL of your API.                                                             | e.g. `http://127.0.0.1:5000/api/filter`   |
| **HTTP method**               | Request method. Defaults to `POST` when not set.                             | e.g. `POST`                               |
| **HTTP Request Headers**      | Custom headers as `KEY=value` pairs, separated by `;`.                       | e.g. `X-Api-Key=mykey;Authorization=Bearer token` |
| **Data**                      | JSON payload. Sent with `Content-Type: application/json`.                    | e.g. `{ "name": "{{ .TorrentName }}" }`   |
| **Expected HTTP status code** | Status code that counts as a pass.                                           | e.g. `200`                                |
| **Retry http status code(s)** | Status codes that trigger a retry, comma separated.                          | e.g. `500,502`                            |
| **Maximum retry attempts**    | How many times to try the request in total.                                  | e.g. `3`                                  |
| **Retry delay in seconds**    | Wait time between attempts.                                                  | e.g. `5`                                  |

### On Error

Each external filter has an **On Error** setting that controls what happens when the script or webhook itself fails (for example a connection error):

- **Reject**: the release is rejected (default behavior).
- **Continue to next**: the failed external filter is skipped and filtering continues with the next check.

---

---

## Freeleech


Not all indexers implemented in autobrr support freeleech filtering.  
This is due to the indexer simply not announcing freeleech.

This table shows all supported indexers and their freeleech capabilities. This list is updated regularly and automatically.

---

## General


| Field             | Description                                               | Default value |
|-------------------|-----------------------------------------------------------|---------------|
| **Filter name**   | The name of this filter.                                  |               |
| **Enabled**       | Is this filter active?                                    | false         |
| **Indexers**      | Which indexers should this filter work for?               |               |
| **Announce Type** | See [Announce Type](#announce-type) for more information. | NEW           |

### Announce Type

| Type          | Description                                   | Supported By   |
|---------------|-----------------------------------------------|----------------|
| `NEW`         | Newly uploaded releases                       | All indexers   |
| `CHECKED`     | Staff verified/checked releases               | PTP            |
| `PROMO`       | Promotional releases (freeleech/neutral/half) | PTP and others |
| `PROMO_GP`    | Golden Popcorn marked releases                | PTP            |
| `RESURRECTED` | Reseeded/revived releases                     | PTP and others |

:::info
New filters default to `NEW`. If you also want to match staff-checked, promotional or resurrected releases, you must add
those announce types to the filter explicitly. `CHECKED` and `PROMO_GP` are PTP-specific, while `PROMO` and
`RESURRECTED` are also announced by some other trackers.
:::

## Rules

:::tip[About Size]

Some indexers don't announce the size of a release, so autobrr will download the torrent file to get a size.  
This check is only triggered if a minimum or a maximum size in that particular filter has been set.  
For workflows that require an external size check for an external application set `Min. size` to 1.  
To get around downloading every torrent file, some APIs for trackers that are problematic are implemented.

For TV and movies it's advised to use filters like `resolution`, `source` and `codec`  
since these often have known approximate sizes.

:::

| Field                       | Description                                                                                                                                                          | Default value        |
|-----------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------|
| **Min. size**               | Minimum torrent size allowed. Supports units such as MB, MiB, GB, etc.                                                                                               |                      |
| **Max. size**               | Maximum torrent size allowed. Supports units such as MB, MiB, GB, etc.                                                                                               |                      |
| **Delay**                   | Number of seconds to wait before running actions.                                                                                                                    | 0                    |
| **Priority**                | Filters are checked in order of priority. Positive and negative numbers allowed. Higher number = higher priority.                                                    | 0                    |
| **Max downloads**           | Number of max downloads as specified by the respective unit.                                                                                                         | 0 (which means +Inf) |
| **Max downloads per**       | The unit of time for counting the maximum downloads per filter: `HOUR`, `DAY`, `WEEK`, `MONTH` or `EVER`. `EVER` caps the total downloads for the filter's lifetime. |                      |
| **Skip duplicates profile** | The profile describing how to prevent duplicate downloads.  See [Skip Duplicates](skip-duplicates.mdx).                                                               | None                 |

:::info
If "Max downloads" is set, the filter will only match if you have downloaded fewer than "max downloads" items since the
beginning of the "max downloads per" period. For instance, if you set "max downloads" to 3 and "max downloads per" to "
day" the filter won't match unless you have downloaded fewer than 3 items since the beginning of the current day, in
local time.
:::

---

---

## Filter Intro

# Filters

Filters are how you tell autobrr what to grab. Each filter is a set of conditions (resolution, size, release group and so on) that every announce is checked against; when a release matches, the filter's actions run and the release is sent to your download client, an *arr, or whatever else you've configured. You can run as many filters as you like side by side, each with its own indexers, rules and actions.

## How a filter is evaluated {/* #how-a-filter-is-evaluated */}

Every field you set in a filter must match for a release to be approved; fields you leave empty are skipped entirely. A typical TV filter checks a handful of fields against the parsed release name:

If any single check fails, the release is rejected. Rejected releases don't show up on the Releases page; only releases that matched a filter do. To see why something was skipped, check the logs with log level `DEBUG`:

The `Except` fields work the other way around: a match there is a reason to reject. Here the release passes every quality check, but its group is on the filter's except list:

### Check order {/* #check-order */}

Checks run from cheap to expensive, and a failure at any step stops the rest:

The regular fields are checked first, against what the announce itself contains. The gold steps only run when your filter needs a value the announce didn't include: if you set size limits and the indexer doesn't announce size, autobrr fetches it out of band, via the indexer's API where available, or by downloading the .torrent file as a last resort. The same applies to uploader and record label checks on API-enabled indexers. [External filters](./external.mdx) always run last, so your scripts and webhooks are only called for releases that already passed everything else.

The same order as a flowchart; every reject path ends the same way, only a release that clears every step reaches the actions:

[//]: # (---)

## Wildcard matching {/* #wildcard-matching */}

:::info

If you want to match a string partially, then remember to use the `*` around the before/after/around what you're
looking for.
If you want to match a string exactly, then try to avoid the use of the `*` wildcard character.

Exception: the Match/Except releases, description and release tags fields on the [Advanced](advanced.mdx#releases) tab
match substrings even without wildcards and cannot match exactly in non-regex mode.

:::

## Sharing filters {/* #sharing-filters */}

Filters can be exported and imported as JSON, which makes it easy to back them up or share them with others:

- **Export**: Open the dropdown next to a filter in the filter list and pick **Export JSON**, or **Export JSON (Discord)
  ** to get the same JSON wrapped in a Discord code block. The result is copied to your clipboard.
- **Import**: Click the arrow next to **Create Filter** and choose **Import Filter**. It accepts autobrr filter JSON as
  well as autodl-irssi `.tracker` configs, and imported filters are renamed automatically if the name is already taken.

---

---

## Lists

# Lists Overview

Lists allow you to automatically transform monitored media from various sources into autobrr filters:

- Shows, movies, books and music from \*arr applications
- Titles from external services (Trakt, MDBList, Metacritic, etc.)

## Supported list types

| Type       | Description                                                                                                                     |
|------------|---------------------------------------------------------------------------------------------------------------------------------|
| Radarr     | Monitored movies from a Radarr instance.                                                                                        |
| Sonarr     | Monitored shows from a Sonarr instance.                                                                                         |
| Lidarr     | Monitored artists and albums from a Lidarr instance.                                                                            |
| Readarr    | Monitored books from a Readarr instance. Always updates the `Match Releases` field.                                             |
| Whisparr   | Monitored titles from a Whisparr instance, handled like Sonarr.                                                                 |
| Trakt      | Built-in Trakt lists, or your own Trakt list URL. Private lists require a Trakt API key (client ID); the built-ins need no key. |
| MDBList    | Lists from [mdblist.com](https://mdblist.com).                                                                                  |
| Metacritic | Album lists (built-ins for upcoming and new albums).                                                                            |
| Plaintext  | A plain text file with one title per line, from a URL or a local file. See [Plaintext lists](#plaintext-lists).                 |
| Steam      | A Steam wishlist. Use the wishlist data URL: `https://store.steampowered.com/wishlist/id/USERNAME/wishlistdata`.                |
| AniList    | The built-in autobrr-hosted anime lists, or any URL returning the same JSON shape.                                              |

## Built-in lists

We have a couple built in lists that we maintain/update via our api. You can use your own urls in the fields but these
below are available as built-ins.

| Type       | Lists                                                                             |
|------------|-----------------------------------------------------------------------------------|
| MDBList    | `Latest TV Shows`                                                                 |
| Trakt      | `Anticipated TV`, `Popular TV`, `Upcoming Movies`, `Upcoming BluRay`, `Steven Lu` |
| Metacritic | `Upcoming Albums`, `New Albums`                                                   |
| AniList    | `Current anime season`, `Trending animes`, `Next anime season`                    |

## Quick Setup Guide

### 1. Access Lists Settings

Navigate to `Settings -> Lists` to begin setup.

### 2. Create a New List

1. Click "Add new list"
2. Fill in the basic settings:
    - List name
    - Select type (e.g., Radarr, Sonarr)
    - Choose instance

### 3. Optional Configuration

- **Match Releases**: Uses `Match Releases` field instead of `Movies/Shows` field
- **Include Unmonitored**: Includes unmonitored titles (useful for cross-seed filters)
- **Alternate Titles**: Includes alternate titles in the filter
- **Tags Included / Tags Excluded**: Radarr and Sonarr lists only. Only include items carrying one of the included tags,
  or skip items carrying an excluded tag. Matched against the tag labels in the arr instance; items without tags are
  skipped when Tags Included is set.
- **Include Year**: MDBList only. Appends the release year to movie titles as `Title*2024*` for more precise matching.
  Applies to movies only and requires (and auto-enables) Match Releases.
- **Skip clean/sanitize**: Plaintext only. By default all titles are sanitized into wildcard patterns (punctuation
  replaced with `?`/`*`); this toggle uses the list content as-is.

:::info
Lists also support custom HTTP request headers as `Key=Value` pairs for sources behind authentication. This is currently
only settable via the [API](../api.mdx), not the web UI.
:::

### 4. Finalize Setup

1. Select target filter(s)
2. Click "Save"

> **Note**: Filters update immediately upon save and refresh every 6 hours automatically.

## Filter Customization

You can improve filtering further by configuring fields like:

- Resolutions
- Categories
- Other filter criteria

Lists will only overwrite the specific fields they manage during updates.

## Plaintext lists

Plaintext lists read one title per line and turn the titles into a filter update.

- **Remote**: any `http(s)://` URL, as long as it serves the file with the `text/plain` content type.
- **Local file**: a `file://` URL pointing to a file on the same machine as autobrr, e.g.
  `file:///home/username/list.txt`.

Titles are sanitized into wildcard patterns by default; enable **Skip clean/sanitize** to use them exactly as written.

## Field Usage by List Type

| List Type                                                          | Fields Used                                                          |
|--------------------------------------------------------------------|----------------------------------------------------------------------|
| Music (e.g. Metacritic or Lidarr)                                  | `Artists`, `Albums` (Metacritic can use `Match Releases` if enabled) |
| Movies/TV (e.g. Sonarr, Radarr, Whisparr, Trakt, MDBList, AniList) | `Movies/Shows` (or `Match Releases` if enabled)                      |
| Plaintext                                                          | `Movies/Shows` (or `Match Releases` if enabled)                      |
| Steam                                                              | `Match Releases`                                                     |
| Readarr                                                            | `Match Releases` (always)                                            |

## Automatic Updates via Webhook

### Available Endpoints

| Endpoint                              | Methods      | Description                                    |
|---------------------------------------|--------------|------------------------------------------------|
| `/api/webhook/lists/trigger`          | `POST`,`GET` | Refresh all lists                              |
| `/api/webhook/lists/trigger/arr`      | `POST`,`GET` | Refresh all ARR lists                          |
| `/api/webhook/lists/trigger/lists`    | `POST`,`GET` | Refresh all non-ARR lists                      |
| `/api/webhook/lists/trigger/{listID}` | `POST`       | Refresh a single list by listID (Copy List ID) |

### ARR Setup Instructions

1. In your \*arr application, go to `Settings -> Connect -> Webhook`
2. Configure the webhook:
   ```
   Name: Some name
   Events: On Movie Added, On Movie Deleted
   Method: POST
   URL: https://autobrr.mydomain.com/api/webhook/lists/trigger/arr
   ```

#### Show Advanced Settings

1. Click the cogwheel icon
2. Add header:
    - Key: `X-API-Token`
    - Value: `your-autobrr-api-key`
3. Test and Save

This webhook will trigger filter updates whenever media is added or removed from your \*arr instance.

With the webhook in place the whole loop is automatic: add a movie in Radarr and the filter knows about it seconds later, ready for the next announce:

---

## Macros

Macros are a great way to enhance your workflow by adding custom logic/data processing to the input data provided by autobrr. Macros are currently supported by input fields by Filters, in two sections: Actions and External (filters).

## Implementation

The template functionality is provided by the Go template engine. This is an extremely powerful scripting platform that can perform operations, evaluations, and manipulate values at the user configuration level. Further information on the functionality of this platform can be found [on its official documentation page](https://pkg.go.dev/text/template).

Autobrr enhances the Go template engine with [Sprig template functions](https://masterminds.github.io/sprig/) which provide the possibility for workflows involving more complex logic than initially provided by the Go template engine.

Please take note that Sprig has some of its own edge-cases:

> Most of the [Sprig] regex functions are unfortunately significantly broken when it comes to using them in pipelines. By broken I mean the functions technically work, but their usage I don't think would be intuitive to anyone, and that usage is difficult.
>
> -- <cite>[Open issue on Sprig's Github page](https://github.com/Masterminds/sprig/issues/86)</cite>

Another intricate edge-case from which Sprig suffers from is that every RegEx directive containing a backslash has to be escaped twice. Put another way, what was once a _single_ backslash, now becomes a _double_ backslash. For example, `\d` becomes `\\d`.

## Available functions

For the functions provided by the Go template engine, please reference its [its official documentation page](https://pkg.go.dev/text/template).

Available Sprig function, along with the relevant examples can be found [at Pydio.com](https://pydio.com/en/docs/cells-flows/sprig).

## Available variables

## Examples

Simple examples of this extensive functionality can be found below.

- Escape torrent name - `{{ .TorrentName | js }}`

### Dynamic categories in qBittorrent

Dynamic resolution for eg movies or tv. Very useful to keep things separated and easy to manage. With well-named releases this works great as a Plex library.

Category: `movies-{{ .Resolution }}` = `movies-1080p`, `movies-2160p`

### Tags

Dynamic tags based on indexer, resolution or other

- Tags: `{{ .Indexer }}` = `mockindexer`
- Tags: `{{ .Resolution }}` = `2160p`

### Dynamic date and time

Could be used to build dynamic save paths etc.

- `{{ .CurrentYear }}`
- `{{ .CurrentMonth | printf "%02d"}}`

### Dynamic movie filter with hdr/dv

Category: `movies-{{ .Resolution }}{{ if .HDR }}-{{ .HDR }}{{ end }}`

### Custom regex example

One user in our Discord wanted to have a custom watch folder for TV shows but without the episode in the name.
The best solution we could find was to use... a bit of regex. It's not great, but it's not terrible either.

The relevant query is:

```
{{- $filename := (regexReplaceAll "(?i)(.*).torrent$" (osBase .TorrentPathName) "${1}") -}}
{{- $pattern := "([\\.\\s\\-\\(])([Ss]\\d+)[\\.\\s\\-]?([Ee]\\d+)?([\\.\\s\\-\\)])" -}}
{{- $repl := "${1}${2}${4}" -}}
{{- if ge (len .TorrentName) (len $filename) -}}
  {{- regexReplaceAll $pattern .TorrentName $repl -}}
{{- else -}}
	{{- regexReplaceAll $pattern $filename $repl -}}
{{- end -}}
```

:::info[Heads up]
Do note that the minus (-) signs here denote that the template bars are not allowed to emit/allow any whitespace before/after them (as would've been the case without the minus signs).
:::

---

## Music


A typical music filter checks the announced format, quality, media and release type; every field you set must match, and fields you leave empty are skipped:

---

:::info

If you want to match a string partially, then remember to use the `*` around the before/after/around what you're looking for.
If you want to match a string exactly, then try to avoid the use of the `*` wildcard character.

:::

---

## Music

| Field                    | Description                                                                                | Examples                        |
|--------------------------|--------------------------------------------------------------------------------------------|---------------------------------|
| **Artists**              | Comma separated list of media names to match.                                              | e.g. `That?Artist`              |
| **Albums**               | Comma separated list of acceptable year ranges in the string.                              | e.g. `That?Album, *the?album*`  |
| **Years**                | Comma separated list of acceptable years in the string.                                    | e.g. `2019,2020-2022`           |
| **Match record labels**  | Comma separated list of record labels to match, wildcards supported.                       | e.g. `Deathwish*,Profound Lore` |
| **Except record labels** | Comma separated list of record labels to ignore (takes priority over Match record labels). | e.g. `*bootleg*`                |

:::info
Record label matching is only supported by Redacted and Orpheus. When the announce does not include the record label, autobrr fetches it from the tracker API, which requires the indexer's API key to be configured in autobrr.
:::

### Quality

| Field            | Description                                                                                                                                                                                                                                     |
|------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Format**       | Will only match releases with any of the selected formats.                                                                                                                                                                                      |
| **Quality**      | Will only match releases with any of the selected qualities.                                                                                                                                                                                    |
| **Media**        | Will only match releases with any of the selected media, e.g. `CD`, `Vinyl`, `WEB`.                                                                                                                                                             |
| **Music Type**   | Will only match releases with any of the selected types (`Album`, `Single`, `EP`, etc.). Found under Release Details.                                                                                                                           |
| **Log**          | Whether Log **must** be included.                                                                                                                                                                                                               |
| **Log Score**    | Matches Log percent for indexers that announce it. Requires Log to be enabled, and matches the announced score exactly, not as a minimum: `100` only matches perfect logs. Check your indexer, the announced Log Score might not be in percent. |
| **Cue**          | Enforces Cue requirement.                                                                                                                                                                                                                       |
| **Perfect FLAC** | Overrides all options about quality, source, format, and Cue/Log/Log score. Requires: any media, FLAC, Lossless or 24bit Lossless; if the media is CD, also requires Log with a 100% score.                                                                           |

---

---

## Omegabrr

:::warning[Disclaimer]

As of 2024-12-26 the omegabrr functionality has been implemented in autobrr and this service is immediately deprecated and unsupported.
See [Lists](./lists.mdx) for information about how to use lists in autobrr.

:::

---

## Skip Duplicates

The Skip Duplicates feature is intended to prevent duplicate downloads.  But what exactly is a duplicate and what are "skip duplicate profiles"?

## Overview

A filter will reject a release as a duplicate if
* you have selected a profile in the `Skip Duplicates Profile` selector on the General tab
* the release in question matches a prior release approved by any filter (see [Determining a Match](#determining-a-match))
* the prior approval is "finished", meaning all actions have completed successfully (see [Limitations and Recommendations](#limitations-and-recommendations))

## Determining a Match

Release names are parsed into fields based solely on the release name.
This is complicated, so it is delegated to the [rls package](https://github.com/moistari/rls).
These fields are then compared against the fields defined in the `skip duplicates profile`
(which on the Settings >> Releases page is called `Release Duplicate Profiles`).

For example, the `TV` profile by default contains `Title`, `Year`, `Month`, `Day`, `Season`, `Episode`.
Therefore, the `TV` profile will consider these to be duplicates:
* `Perseverance S02E09 1080p HEVC x265-MuyBueno`
* `Perseverance S02E09 720p x265-Tipico`

because all fields defined in the profile match.  Note that in this example, Year, Month, and Day are all parsed as 0,
so they match.  If the release name contains a year, it will not match:
* `Perseverance 2022 S02E09 720p x265-NoBueno`

If you want to disregard the Year, you could either
1. Add a new profile, e.g. "Episodic TV" and do not include Year, Month, and Day, or
2. Edit the `TV` profile to remove Year, Month, and Day

Profiles can also match on `Hybrid`, which treats hybrid releases (like hybrid remuxes) as distinct from their non-hybrid counterparts instead of skipping them as duplicates.

## Limitations and Recommendations

The major limitation is that a filter action needs to have completed successfully (marked FILTER_APPROVED)
*before* the duplicate is announced.  During the time a filter is being processed, it is marked FILTER_PENDING.
Therefore, you want to ensure your filter actions complete quickly.

Recommendations:
* Disable qBittorrent reannounce.  In the `qBittorrent` action, under `Announce`, tick `Disable reannounce`.  This logic keeps reannouncing the torrent until the tracker is OK or until the retries are exhausted (2m55s by default).  This opens a large window for duplicate announcements to arrive.
* Use a separate reannounce script.  In qBittorrent under `Settings` >> `Downloads` >> `Run external program`, set `Run external program on torrent added` to a script that does the same thing.  We recommend [qbt](https://github.com/ludviglundgren/qbittorrent-cli).  Usage:
  ```
  qbt torrent reannounce --hash "%I"
  ```

Note: If you run qBittorrent inside a container, then you must install `qbt` inside that container.

---

## TV & Movies


:::info

If you want to match a string partially, then remember to use the `*` around the before/after/around what you're
looking for.
If you want to match a string exactly, then try to avoid the use of the `*` wildcard character.

:::

---

| Field            | Description                                                        | Examples                 |
|------------------|--------------------------------------------------------------------|--------------------------|
| **Movies/Shows** | Comma separated list of media names to match.                      | e.g. `That?Movie, *the*` |
| **Years**        | Comma separated list of acceptable year ranges in the string.      | e.g. `2019,2020-2022`    |
| **Seasons**      | Comma separated list of acceptable TV show seasons in the string.  | e.g. `1,3-6`             |
| **Episodes**     | Comma separated list of acceptable TV show episodes in the string. | e.g. `1,2,10-20`         |
| **Months**       | Comma separated list of acceptable months, for daily shows.        | e.g. `4,2-9`             |
| **Days**         | Comma separated list of acceptable days, for daily shows.          | e.g. `1,15-30`           |

:::info

Months and Days apply to daily shows, where releases are named with a full date (like `2026 07 12`) instead of a season
and episode. They use the same comma/range syntax as Years.

:::

:::info

The Movies/Shows field operates on the _parsed_ media title. This means it is guaranteed not contain dots and
underscores, often found in release strings. However, it's still better to err on the safer side and use the `?`
wildcard character instead.

:::

## Smart Episode

When **Smart Episode** is enabled, the filter will not match episodes older than the last one it matched. Each incoming
episode is compared against the newest release this filter has already pushed and approved for the same show: it only
matches if its season and episode (or year, month and day for daily shows) is newer.

This is useful to avoid grabbing older episodes when you start following a show mid-season, or when an indexer announces
older content again.

:::info

Repacks and propers of an episode you already grabbed are still allowed through: an incoming repack is only blocked by a
newer approved repack from the same release group, and an incoming proper only by a newer approved proper. Releases
without season/episode or date information always pass the check.

:::

## Quality

| Field            | Description                                                                                                                                                                                                                      |
|------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Resolutions**  | Will match releases which contain any of the selected resolutions.                                                                                                                                                               |
| **Sources**      | Will match releases which contain any of the selected sources.                                                                                                                                                                   |
| **Codecs**       | Will match releases which contain any of the selected codecs.                                                                                                                                                                    |
| **Containers**   | Will match releases which contain any of the selected containers.                                                                                                                                                                |
| **Match HDR**    | Will match releases which contain any of the selected HDR designations. Dual-format releases (like `DV HDR10`) only match via the combined options (`DV HDR`, `DV HDR10`, `DV HDR10+`); selecting only `DV` will not match them. |
| **Except HDR**   | Won't match releases which contain any of the selected HDR designations (takes priority over Match HDR). Select all to reliably exclude dual-format releases too.                                                                |
| **Match Other**  | Will match releases which contain any of the selected designations.                                                                                                                                                              |
| **Except Other** | Won't match releases which contain any of the selected Other designations (takes priority over Match Other).                                                                                                                     |

---

## Installation instructions for docker

# Docker

This guide expects some previous docker knowledge and an already working environment.

## docker compose {/* #docker-compose */}

`docker compose` for autobrr. Modify if running with unRAID or setting up with Portainer.

- Logging is optional
- Host port mapping might need to be changed to not collide with other apps
- Change `BASE_DOCKER_DATA_PATH` to match your setup. Can be simply `./data`
- Set custom network if needed
- Set the `user: 1000:1000` to correct ID of your user.

```yaml title="docker-compose.yml"
services:
  autobrr:
    container_name: autobrr
    image: ghcr.io/autobrr/autobrr:latest
    restart: unless-stopped
    #logging:
    #  driver: json-file
    #  options:
    #    max-file: ${DOCKERLOGGING_MAXFILE}
    #    max-size: ${DOCKERLOGGING_MAXSIZE}
    user: 1000:1000
    environment:
      - TZ=${TZ}
    volumes:
      - ${BASE_DOCKER_DATA_PATH}/autobrr/config:/config
    ports:
      - 7474:7474
```

### Environment variables {/* #environment-variables */}

We support the following environment variables to override the config file:

```yaml title="docker-compose.yml"
services:
  autobrr:
    environment:
      - AUTOBRR__HOST=string
      - AUTOBRR__PORT=string
      - AUTOBRR__BASE_URL=string
      - AUTOBRR__BASE_URL_MODE_LEGACY=bool
      - AUTOBRR__LOG_LEVEL=string
      - AUTOBRR__LOG_PATH=string
      - AUTOBRR__LOG_MAX_SIZE=string/int without MB
      - AUTOBRR__LOG_MAX_BACKUPS=string/int
      - AUTOBRR__SESSION_SECRET=string # legacy, unused since v1.66.0 (sessions are stored in the database)
      - AUTOBRR__CUSTOM_DEFINITIONS=string
      - AUTOBRR__CHECK_FOR_UPDATES=bool
      - AUTOBRR__DATABASE_TYPE=sqlite/postgres
      - AUTOBRR__DATABASE_DSN=string # alternative to the individual postgres* variables
      - AUTOBRR__DATABASE_MAX_BACKUPS=int # positive values only, 0 is ignored
      - AUTOBRR__POSTGRES_HOST=string
      - AUTOBRR__POSTGRES_PORT=string
      - AUTOBRR__POSTGRES_SOCKET=string # connect via unix socket, replaces host/port
      - AUTOBRR__POSTGRES_DATABASE=string
      - AUTOBRR__POSTGRES_USER=string
      - AUTOBRR__POSTGRES_PASS=string
      - AUTOBRR__POSTGRES_SSLMODE=string
      - AUTOBRR__POSTGRES_EXTRA_PARAMS=string
      - AUTOBRR__CORS_ALLOWED_ORIGINS=string
      - AUTOBRR__PROFILING_ENABLED=bool
      - AUTOBRR__PROFILING_HOST=string
      - AUTOBRR__PROFILING_PORT=int
      - AUTOBRR__OIDC_ENABLED=bool
      - AUTOBRR__OIDC_ISSUER=string
      - AUTOBRR__OIDC_CLIENT_ID=string
      - AUTOBRR__OIDC_CLIENT_SECRET=string
      - AUTOBRR__OIDC_REDIRECT_URL=string
      - AUTOBRR__OIDC_DISABLE_BUILT_IN_LOGIN=bool
      - AUTOBRR__METRICS_ENABLED=bool
      - AUTOBRR__METRICS_HOST=string
      - AUTOBRR__METRICS_PORT=int
      - AUTOBRR__METRICS_BASIC_AUTH_USERS=string
```

:::tip[Docker secrets]
Every variable also accepts a `_FILE` variant whose value is read from the referenced file, e.g. `AUTOBRR__POSTGRES_PASS_FILE=/run/secrets/pg_pass`. This is meant for Docker/Podman secrets. The `_FILE` variant takes precedence over the plain variable, and the file content is trimmed of surrounding whitespace.
:::

:::info
`AUTOBRR__POSTGRES_DB` and `AUTOBRR__POSTGRES_PASSWORD` are accepted as aliases for `AUTOBRR__POSTGRES_DATABASE` and `AUTOBRR__POSTGRES_PASS`. They match the official postgres image variable names, which is convenient when sharing an env file with the postgres container. The aliases take precedence when both are set.
:::

### Manually configure autobrr (optional) {/* #manually-configure-autobrr */}

You can either let autobrr create the config itself at startup, or create one manually. For more information, please visit [configuring autobrr](../configuration/autobrr.mdx) which covers creating a user manually, configuring the default port, setting the desired log level, etc.

### Start the container {/* #start-the-container */}

```shell
docker compose up -d
```

## Listen address {/* #listen-address */}

:::info

By default autobrr listens on `127.0.0.1` out of security considerations. Even though autobrr has built-in Docker detection and automagically adjusts the listen address, it is recommended to manually set the listen address (in `config.toml`) to `0.0.0.0` in case you run into problems with your setup.

:::

## Reverse proxy (recommended) {/* #reverse-proxy-recommended */}

## Finishing up {/* #finishing-up */}

Now it's up and running, and you should be able to visit it at `autobrr.domain.ltd` or `domain.ltd:7474` and login. Check out the next pages for further setup.

---

## Installation instructions

# Installation

autobrr ships as a single binary with the web UI built in, so installing it mostly comes down to getting that binary running on whatever you already have. Pick the guide that matches your setup.

## Pick your setup {/* #pick-your-setup */}

### Seedbox {/* #seedbox */}

If you rent a seedbox, start with the [Seedbox guide](./seedbox.mdx). Most shared providers (Ultra.cc, Whatbox, HostingByDesign, Swizzin-based boxes and others) offer a one-click installer or an install script, so you never need root access. The guide also covers dedicated seedboxes.

### Linux server {/* #linux */}

For your own VPS, home server or NAS, follow the [Linux guide](./linux.mdx). You download the binary and run it as a systemd service so it starts on boot and restarts on failure. This is the recommended setup when you control the machine.

### Docker {/* #docker */}

Already running your stack in containers? The [Docker guide](./docker.mdx) covers the official `ghcr.io/autobrr/autobrr` image with a compose example, which slots in next to your existing qBittorrent, Sonarr and Radarr containers.

### macOS {/* #macos */}

On a Mac, the [macOS guide](./macos.mdx) uses Homebrew: `brew install autobrr`, then `brew services start autobrr` to keep it running in the background.

### Windows {/* #windows */}

The [Windows guide](./windows.mdx) sets autobrr up as a background service, so it runs 24/7 without a command prompt window open.

## Good to know {/* #good-to-know */}

- Whatever the platform, you end up with the same thing: autobrr serving its web UI on port `7474`, ready to be configured in the browser.
- autobrr uses SQLite by default, which suits most setups. If you expect a large release history you can use [PostgreSQL](./supplementary/postgresql.mdx) instead.
- To reach the web UI from outside, see the [reverse proxy guides](./reverse-proxy/index.mdx), with examples for Caddy, lighttpd, nginx, SWAG, Traefik and Tailscale Serve.
- Moving to a new box later? [Transfer your installation](./supplementary/transfer-installation.mdx) walks through bringing your filters, indexers and settings along.

## After installing {/* #after-installing */}

Once autobrr is running, head to the [Configuration guide](../configuration/autobrr.mdx) to set up your [indexers](../configuration/indexers.mdx), IRC connections and download clients.

Stuck at any point? Ask in the [community](../community.mdx); there are over 5,500 people on the Discord, and plenty of them have set up exactly what you're trying to build.

---

## Installation instructions for linux servers

# Linux

Follow the instructions below for recommended setup on a typical Linux server.
Alternatively, see the installation instructions for [Docker ](./docker.mdx) and [Windows ](./windows.mdx).

## Seedbox solutions

See the [Seedbox](seedbox.mdx) page for instructions on how to install autobrr on popular seedbox solutions.

## Regular installation

### Download

Download the latest release, or download the [source code ](https://github.com/autobrr/autobrr/releases/latest) and build it yourself using `make build`.

```bash
wget $(curl -s https://api.github.com/repos/autobrr/autobrr/releases/latest | grep download | grep linux_x86_64 | cut -d\" -f4)
```

### Unpack

```bash
sudo tar -C /usr/local/bin -xzf autobrr*.tar.gz
```

This will extract both `autobrr` and `autobrrctl` to `/usr/local/bin`.

:::info
If you do not have root, or are on a shared system, place the binaries somewhere in your home directory like `~/.bin` or use our installers for [shared seedboxes](seedbox.mdx).
:::

### Configuration

Create the config dir

```bash
mkdir -p ~/.config/autobrr
```

#### Manually configure autobrr (optional)

You can either let autobrr create the config itself at startup, or create one manually. For more information, please visit [configuring autobrr](../configuration/autobrr) which covers creating a user manually, configuring the default port, setting the desired log level, etc.

### Systemd (recommended)

On Linux-based systems, it is recommended to run autobrr as a service with auto-restarting capabilities, in order to account for potential downtime. The most common way is to do it via systemd.

You will need to create a service file in `/etc/systemd/system/` called `autobrr@.service`. The `@` is important.

```bash
touch /etc/systemd/system/autobrr@.service
```

Then place the following content inside the file (e.g. via nano/vim/ed):

```systemd title="/etc/systemd/system/autobrr@.service"
[Unit]
Description=autobrr service for %i
After=syslog.target network-online.target

[Service]
Type=simple
User=%i
Group=%i
ExecStart=/usr/local/bin/autobrr --config=/home/%i/.config/autobrr/

[Install]
WantedBy=multi-user.target
```

The `%i` will automatically be replaced with your user when you call `systemctl enable` with `@USERNAME` like below.

Start the service. Enable will make it startup on reboot. Replace `USERNAME` with your username.

```bash
sudo systemctl enable --now autobrr@USERNAME.service
```

Make sure it's running and `active`

```bash
sudo systemctl status autobrr@USERNAME.service
```

## Listen address

:::info

By default autobrr listens on `127.0.0.1` which is the recommended way when running a reverse proxy, but if you want to expose it to the internet/network then you must change the `host` in the `~/.config/autobrr/config.toml` from `127.0.0.1` to `0.0.0.0`.

Save the changes and restart autobrr with `sudo systemctl restart autobrr@USERNAME.service`.

:::

## Reverse proxy (recommended)

## Finishing up

Now that autobrr is up and running, you should be able to visit the your web UI at `http://YOUR_IP:7474` or `http://domain.ltd:7474` and proceed with your registration/login.

## Version Updates

To upgrade Autobrr to the latest version first stop the service (if you have configured it):

```bash
sudo systemctl stop autobrr@USERNAME.service
```

Download the latest release:

```bash
wget $(curl -s https://api.github.com/repos/autobrr/autobrr/releases/latest | grep download | grep linux_x86_64 | cut -d\" -f4)
```

And finally unpack the release:

```bash
sudo tar -C /usr/local/bin -xzf autobrr*.tar.gz
```

This will overwrite both `autobrr` and `autobrrctl` in `/usr/local/bin`.

---

## Installation instructions for macOS

# macOS

In this setup we will create an autobrr user and a macOS service that operates in the background. This way we won't need to have a command prompt window open 24/7.

## Homebrew

[Homebrew](https://brew.sh/) is a free and open-source software package management system that simplifies the installation of software on macOS and Linux. Known as "the missing package manager for macOS," it extends or fills gaps in the standard software management offerings on these operating systems. Homebrew allows users to easily install, update, and manage software packages and their dependencies through simple commands in the terminal.

### Install Homebrew

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

Alternatively use their `.pkg` installer. Download it from [Homebrew's latest GitHub release](https://github.com/Homebrew/brew/releases/latest).

### Install autobrr

```bash
brew install autobrr
```

### Run

To start autobrr now and restart at login:

```bash
brew services start autobrr
```

Or, if you don't want/need a background service you can just run:

```bash
/opt/homebrew/opt/autobrr/bin/autobrr --config /opt/homebrew/var/autobrr/
```

## Listen address

:::info

By default autobrr listens on `127.0.0.1` which is the recommended way when running a reverse proxy, but if you want to expose it to the internet/network then you must change the `host` in the `config.toml` from `127.0.0.1` to `0.0.0.0`.

Restart autobrr after.
:::

## Reverse proxy (recommended)

You can install nginx on macOS with Homebrew:

```bash
brew install nginx
```

## Finishing up

Now that autobrr is up and running, you should be able to visit the your web UI at `http://YOUR_IP:7474` or `http://domain.ltd:7474` and proceed with your registration/login.

## Version Updates

To upgrade Autobrr to the latest version first stop the service (if you have configured it):

```bash
brew services stop autobrr
```

Upgrade:

```bash
brew update
brew upgrade autobrr
brew services start autobrr
```

---

## Caddy

#### Subdomain (Simple) {/* #caddy-simple-subdomain */}

```nginx title="Caddyfile"
autobrr.example.com {
    reverse_proxy :7474
}
```

#### Subfolder {/* #caddy-subfolder */}

```nginx title="Caddyfile"
example.com/autobrr/* {
    uri strip_prefix /autobrr
    reverse_proxy :7474
}
```

:::info[Heads up]
In case you are using the subfolder option, don't forget to configure the `baseUrl` option for autobrr:

```toml title="config.toml"
# Base url
# Set custom baseUrl eg /autobrr/ to serve in subdirectory.
# Not needed for subdomain, or by accessing with the :port directly.
#
# Optional
#
baseUrl = "/autobrr/"
```
:::

#### Subdomain (Advanced) {/* #caddy-advanced-subdomain */}

```nginx title="Caddyfile"
# Defaults
{
    admin off
    email YOUREMAIL@YOURDOMAIN.COM
    key_type p256
}

(tls) {
    tls {
        protocols tls1.2 tls1.3
        ciphers TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
    }
}

(headers) {
    header {
        -Server
        Strict-Transport-Security "max-age=63072000"

        # Opt-out search engines
        X-Robots-Tag "noindex, nofollow, nosnippet, noarchive"
    }
}

(encoding) {
    encode zstd gzip
}

# Services
autobrr.yourdomain.com {
    reverse_proxy http://autobrr:7474

    import tls
    import headers
    import encoding
}
```

---

## Reverse proxy overview

# Reverse proxy

Running autobrr behind a reverse proxy is recommended when you want to reach the web UI from outside the box it runs on. The proxy gives you TLS, a proper domain instead of `ip:port`, and more robust authentication options.

Pick the guide for the proxy you run:

- [Caddy](./caddy.mdx); the simplest option, with automatic TLS
- [lighttpd](./lighttpd.mdx)
- [nginx](./nginx.mdx)
- [SWAG](./swag.mdx); nginx preconfigured for Docker setups
- [Traefik](./traefik.mdx); common in Docker and Kubernetes stacks
- [Tailscale Serve](./tailscale-serve.mdx); private access over your tailnet, no ports exposed

## Good to know

- By default autobrr listens on `127.0.0.1`, which is exactly what you want with a reverse proxy on the same machine. If the proxy runs elsewhere, change `host` in `config.toml` to `0.0.0.0` and restart autobrr.
- Serving autobrr from a subdirectory like `domain.tld/autobrr/`? Set the `baseUrl` option in `config.toml`; the individual guides show this where it applies. On autobrr v1.55.0 and later you can also set `baseUrlModeLegacy = false` to skip URL rewrites in the proxy. See the [configuration guide](../../configuration/autobrr.mdx) for details.
- Subdomains like `autobrr.domain.tld` need no `baseUrl` at all.

---

## lighttpd

#### Subfolder {/* #lighttpd-subfolder */}

```lighttpd
server.modules += ("mod_proxy")
$HTTP["url"] =^ "/autobrr/" {
    proxy.server = ( "" => (( "host" => "127.0.0.1", "port" => 7474 )))
    proxy.header = ( "upgrade" => 1, "map-urlpath" => ("/autobrr" => "") )
}
```

:::info[Heads up]
Don't forget to set the `baseUrl` option in the `config.toml`:

```toml
# Base url
# Set custom baseUrl eg /autobrr/ to serve in subdirectory.
# Not needed for subdomain, or by accessing with the :port directly.
#
# Optional
#
baseUrl = "/autobrr/"
```

:::

#### Subdomain {/* #lighttpd-subdomain */}

```lighttpd
server.modules += ("mod_proxy")
$HTTP["host"] == "autobrr.domain.com" {
    proxy.server = ( "" => (( "host" => "127.0.0.1", "port" => 7474 )))
    proxy.header = ( "upgrade" => 1 )
}
```

:::info[Heads up]
Don't forget to set the `server.stream-response-body = 1` option in the `lighttpd.conf` otherwise the logs will be blank.

#### Resources {/* #lighttpd-links */}

- [lighttpd wiki](https://wiki.lighttpd.net)
- [lighttpd TLS](https://wiki.lighttpd.net/Docs_SSL)
- [lighttpd mod_proxy](https://wiki.lighttpd.net/mod_proxy)
- [lighttpd mod_auth](https://wiki.lighttpd.net/mod_auth)

---

## Nginx

#### Subfolder {/* #nginx-subfolder */}

```nginx
location /autobrr/ {
    proxy_pass              http://127.0.0.1:7474;
    proxy_http_version      1.1;
    proxy_set_header        X-Forwarded-Host        $http_host;
    proxy_set_header        X-Forwarded-Proto       $scheme;

    #auth_basic "What's the password?";
    #auth_basic_user_file /etc/htpasswd;

    #rewrite ^/autobrr/(.*) /$1 break; # required for versions < v1.55.0, or when baseUrlModeLegacy = true in v1.55.0+
}
```

:::info[Heads up]
Don't forget to set the `baseUrl` option in the `config.toml`:

```toml
# Base url
# Set custom baseUrl eg /autobrr/ to serve in subdirectory.
# Not needed for subdomain, or by accessing with the :port directly.
#
# Optional
#
baseUrl = "/autobrr/"
```

:::

#### Subdomain {/* #nginx-subdomain */}

```nginx
server {
    listen 80;
    server_name autobrr.domain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name autobrr.domain.com;

    include snippets/ssl-params.conf;

    ssl_certificate /etc/nginx/ssl/autobrr.domain.com/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/autobrr.domain.com/key.pem;

    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $http_connection;

    #auth_basic "What's the password?";
    #auth_basic_user_file /etc/htpasswd;

    location / {
        proxy_pass http://127.0.0.1:7474;
    }
}
```

---

## Swag

A basic `swag` config for running on subdomain.

```yaml
server {
    listen 443 ssl;
    listen [::]:443 ssl;

    server_name autobrr.*;

    include /config/nginx/ssl.conf;

    client_max_body_size 0;

    # enable for ldap auth, fill in ldap details in ldap.conf
    #include /config/nginx/ldap.conf;

    # enable for Authelia
    #include /config/nginx/authelia-server.conf;

    location / {
        # enable the next two lines for http auth
        #auth_basic "Restricted";
        #auth_basic_user_file /config/nginx/.htpasswd;

        # enable the next two lines for ldap auth
        #auth_request /auth;
        #error_page 401 =200 /ldaplogin;

        # enable for Authelia
        #include /config/nginx/authelia-location.conf;

        include /config/nginx/proxy.conf;
        include /config/nginx/resolver.conf;
        include /config/nginx/allowdeny.conf;
        set $upstream_app autobrr;
        set $upstream_port 7474;
        set $upstream_proto http;
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;
    }
}
```

A basic `swag` config for running in a subfolder (don't forget to set the baseurl).

```yaml
location ^~ /autobrr/ {
    # enable the next two lines for http auth
    #auth_basic "Restricted";
    #auth_basic_user_file /config/nginx/.htpasswd;

    # enable for ldap auth (requires ldap-server.conf in the server block)
    #include /config/nginx/ldap-location.conf;

    # enable for Authelia (requires authelia-server.conf in the server block)
    #include /config/nginx/authelia-location.conf;

    # enable for Authentik (requires authentik-server.conf in the server block)
    #include /config/nginx/authentik-location.conf;

    include /config/nginx/proxy.conf;
    include /config/nginx/resolver.conf;
    set $upstream_app 127.0.0.1;
    set $upstream_port 7474;
    set $upstream_proto http;
    proxy_set_header        X-Forwarded-Host        $http_host;
    proxy_pass $upstream_proto://$upstream_app:$upstream_port;
    #rewrite ^/autobrr/(.*) /$1 break; # required for versions < v1.55.0, or when baseUrlModeLegacy = true in v1.55.0+
}
```

---

## Tailscale Serve

## What is Tailscale?

[Tailscale](https://tailscale.com) is a VPN service that makes the devices and applications you own accessible anywhere in the world, securely and effortlessly. It enables encrypted point-to-point connections using the open source [WireGuard](https://www.wireguard.com/) protocol, which means only devices on your private network can communicate with each other.

## Using Tailscale Serve as a Reverse Proxy for autobrr

Tailscale Serve[^1] can be used as a reverse proxy for autobrr, providing a secure and easy way to access your autobrr instance from anywhere in your Tailnet[^2]. This setup also includes automatic HTTPS certification for your subdomain.

### Prerequisites

Before setting up Tailscale Serve for autobrr, ensure that:

1. You have a Tailscale account
2. HTTPS is enabled for your Tailnet in the [Tailscale admin console](https://login.tailscale.com/admin/dns).
3. MagicDNS[^3] is enabled in your Tailnet settings. This allows you to use custom subdomains.

### Docker Compose Setup

Here's an example Docker Compose configuration that sets up autobrr as a Tailscale node in your Tailnet with its own LetsEncrypt[^4] certified subdomain:

```yaml
services:
  autobrr:
    container_name: autobrr
    image: ghcr.io/autobrr/autobrr:latest
    restart: unless-stopped
    user: 1000:1000
    environment:
      - TZ=${TZ}
    volumes:
      - ${BASE_DOCKER_DATA_PATH}/autobrr/config:/config
    network_mode: service:autobrr-ts
    depends_on:
        - autobrr-ts

  autobrr-ts:
    image: tailscale/tailscale:latest
    container_name: autobrr-ts
    hostname: autobrr
    environment:
      - TS_AUTHKEY=${TS_AUTHKEY}
      - TS_EXTRA_ARGS=${TS_EXTRA_ARGS}
      - TS_STATE_DIR=${TS_STATE_DIR}
      - TS_SERVE_CONFIG=/config/autobrr.json
      - TZ=${TZ}
    volumes:
      - tailscale-data-autobrr:/var/lib/tailscale
      - /dev/net/tun:/dev/net/tun
      - ${BASE_DOCKER_DATA_PATH}/config:/config
    cap_add:
      - net_admin
      - sys_module
    restart: unless-stopped

volumes:
  tailscale-data-autobrr:
    driver: local
```

### Setting Up

1. **Create a `config/autobrr.json` file in your project directory with the Tailscale Serve configuration for autobrr**
  ```json title="/config/autobrr.json"
{
    "TCP": {
      "443": {
        "HTTPS": true
      }
    },
    "Web": {
      "${TS_CERT_DOMAIN}:443": {
        "Handlers": {
          "/": {
            "Proxy": "http://127.0.0.1:7474"
          }
        }
      }
    },
    "AllowFunnel": {
      "${TS_CERT_DOMAIN}:443": false
    }
  }
```

  :::info
  There is no need to set environment variable for `TS_CERT_DOMAIN`. It pulls that directly from your account.
  :::

2. **Generate a Tailscale auth key**
   - Go to the [Tailscale Admin Console](https://login.tailscale.com/admin/settings/keys)
   - Click on "Generate auth key"

3. **Set up the required environment variables in a `.env` file**
  ```toml title=".env"
  BASE_DOCKER_DATA_PATH=/path/to/your/docker/data
  TZ=UTC

  TS_AUTHKEY=tskey-auth-adKJA23Skjhad-ASDoiqQoas1dQWda41sohi
  TS_EXTRA_ARGS=--advertise-tags=tag:container --reset
  TS_STATE_DIR=/var/lib/tailscale
  ```

4. **Run `docker compose up -d` to start the services**

Once running, your autobrr instance will be accessible through your Tailnet using the configured subdomain with HTTPS enabled.

:::info
You need to approve this node before it can be accessed. You can do so in your Admin Console here: [https://login.tailscale.com/admin/machines](https://login.tailscale.com/admin/machines)
:::

## Benefits

- Secure access to your autobrr instance from anywhere in your Tailnet
- Automatic HTTPS certification for your subdomain
- No need for port forwarding or complex firewall rules

## Tips

### Expose to the Wide Internet

If you want to expose your autobrr instance to be available outside your Tailnet, you need to:

1. **Set `AllowFunnel: true` in `/config/autobrr.json`:**
   ```json
   "AllowFunnel": {
     "${TS_CERT_DOMAIN}:443": true
   }
   ```

2. **Add this to your policy in your [Access Controls](https://login.tailscale.com/admin/acls/file):**
   ```json
   "nodeAttrs": [
     {"target": ["tag:container"], "attr": ["funnel"]},
   ],
   ```

:::caution
Ensure you have a strong and unique password for autobrr when doing this.
Funnel is only needed if you want access to autobrr from a device that is not connected to your Tailnet.
:::

### Troubleshooting

If you encounter issues:

1. Check the Tailscale logs: `docker logs autobrr-ts`
2. Verify that MagicDNS and HTTPS are enabled in your Tailnet settings
3. Ensure the `TS_AUTHKEY` is valid and has not expired

A great video by Alex Kretzschmar talking about Tailscale in Docker:

## Conclusion

Using Tailscale Serve as a reverse proxy for autobrr provides a secure and convenient way to access your instance from anywhere. It simplifies the setup process and provides automatic HTTPS certification.

[^1]: Read more about Tailscale Serve in the official docs: https://tailscale.com/kb/1242/tailscale-serve
[^2]: A Tailnet is your private network created by Tailscale, encompassing all your devices and users.
[^3]: MagicDNS is a Tailscale feature that automatically gives DNS names to the devices on your network, making them easier to access.
[^4]: Let's Encrypt is a free, automated, and open Certificate Authority providing trusted certificates for HTTPS encryption.

---

## Traefik

Traefik setup to run on subdomain.

- Needs an `.env` file with `DOMAIN` set, like `DOMAIN=something.local`
- Expects an externally created network called `proxy`
- Expects two `entryPoints`: `http` going to `:80` and `https` going to `:443`
- Expects a `certificateResolver` called `letsencrypt`

Your config may be different so change accordingly.

### Subdomain

```yaml title="docker-compose.yml"
version: "3.7"

networks:
  proxy:
  external: true

services:
  autobrr:
    image: ghcr.io/autobrr/autobrr:latest
    container_name: autobrr
    restart: unless-stopped
    networks:
      - proxy
    volumes:
      - ./data:/config
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=proxy"

      - "traefik.http.middlewares.redirect-https.redirectScheme.scheme=https"
      - "traefik.http.middlewares.redirect-https.redirectScheme.permanent=true"

      - "traefik.http.routers.autobrr-https.rule=Host(`autobrr.$DOMAIN`)"
      - "traefik.http.routers.autobrr-https.entrypoints=https"
      - "traefik.http.routers.autobrr-https.tls=true"
      - "traefik.http.routers.autobrr-https.tls.certresolver=letsencrypt"
      - "traefik.http.routers.autobrr-https.service=autobrr"
      - "traefik.http.routers.autobrr-http.rule=Host(`autobrr.$DOMAIN`)"
      - "traefik.http.routers.autobrr-http.entrypoints=http"
      - "traefik.http.routers.autobrr-http.middlewares=redirect-https"
      - "traefik.http.routers.autobrr-http.service=autobrr"
      - "traefik.http.services.autobrr.loadbalancer.server.port=7474"
```

### Subfolder

```yaml
labels:
  - "traefik.enable=true"
  - "traefik.docker.network=proxy"

  - "traefik.http.middlewares.autobrr-strip.stripprefix.prefixes=/autobrr"
  - "traefik.http.middlewares.autobrr-strip.stripprefix.forceSlash=true"

  - "traefik.http.routers.autobrr-baseurl.rule=Host(`full.domain.com`) && PathPrefix(`/autobrr`)"
  - "traefik.http.routers.autobrr-baseurl.middlewares=autobrr-strip"
  - "traefik.http.routers.autobrr-baseurl.entrypoints=https"
  - "traefik.http.routers.autobrr-baseurl.tls=true"
  - "traefik.http.routers.autobrr-baseurl.tls.certresolver=letsencrypt"
  - "traefik.http.routers.autobrr-baseurl.service=autobrr-baseurl"
  - "traefik.http.services.autobrr-baseurl.loadbalancer.server.port=7474"
```

---

## autobrr installation instructions for dedicated seedboxes and shared (non-root) seedbox solutions like giga-rapid, hostingby.design, swizzin.net, ultra.cc, whatbox, seedhost, feralhosting, bytesized-hosting and rapidseedbox.

# Seedbox installation

## Dedicated Seedbox

These are instructions and installation scripts for dedicated seedboxes with the most common solutions. See [Linux](./linux.mdx) if you are running a different setup.

### Saltbox

Saltbox documentation: [https://docs.saltbox.dev/apps/autobrr/](https://docs.saltbox.dev/apps/autobrr/)

#### Installation

```shell
sb install autobrr
```

### Swizzin CE

Swizzin documentation: [https://swizzin.ltd/applications/autobrr](https://swizzin.ltd/applications/autobrr)

#### Installation

```shell
sudo box install autobrr
```

#### Update

```shell
sudo box upgrade autobrr
```

### Quickbox

Quickbox documentation: [https://quickbox.io/knowledge-base/autobrr-quick-reference/](https://quickbox.io/knowledge-base/v3/applications-v3/autobrr-applications-v3/autobrr-quick-reference/)

#### Installation

```shell
qb install autobrr
```

## Shared Seedbox

These are instructions and installation scripts for shared seedboxes. We have support for a few providers out of the box, but if yours are missing, then please reach out on [Discord ](https://discord.autobrr.com/) so we can add support for it.

The scripts require some input but do most of the work.

### Bytesized

#### Installation & Update

```shell
wget https://get.autobrr.com/autobrr/bytesized && bash ./bytesized
```

### Feralhosting

#### Installation & Update

```shell
wget https://get.autobrr.com/autobrr/feral && bash ./feral
```

### GigaRapid

:::info

Giga-Rapid.com provides a OneClick installer through their panel.  
Please use this installer to install or update autobrr.

:::

### HostingByDesign

_Previously known as seedbox.io_

#### Installation

```shell
box install autobrr
```

#### Update

```shell
box upgrade autobrr
```

### Rapidseedbox

:::info

rapidseedbox.com provides a OneClick installer through their panel.
Please use this installer to install or update autobrr.

:::

### Swizzin.net

#### Installation

```shell
box install autobrr
```

#### Update

```shell
box upgrade autobrr
```

### Ultra.cc

:::info

Ultra.cc provides a OneClick installer through their panel.  
Please use this installer to install or update autobrr.

:::

### Whatbox.ca

:::info

Whatbox.ca provides a OneClick installer through their panel.
Please use this installer to install autobrr.
They maintain a custom autobrr installation and keep it up-to-date.

:::

### Others

#### Installation & Update

The seedbox.io installer might work for other providers, but if not reach out in Discord.

```shell
wget https://get.autobrr.com/autobrr/sbio && bash ./sbio
```

Note: Remember to head over to our [Configuration Guide](../configuration/indexers.mdx) to learn how to set up your indexers, IRC, and download clients after you're done installing.

---

## Setup autobrr with PostgreSQL

# PostgreSQL

Using PostgreSQL is entirely optional and is geared towards more advanced users (the 0.1%). The reason you might want to use PostgreSQL is that it handles huge databases much better than SQLite, which comes bundled with the main autobrr application.

Nevertheless, if you want to use PostgreSQL with autobrr, then add this to your autobrr configuration file and restart your autobrr instance (see the next chapter if you want to convert an existing SQLite database):

```toml title="config.toml"
# Database config
#
databaseType = "postgres"
postgresHost = "localhost"
postgresPort = 5432
postgresDatabase = "autobrr"
postgresUser = "autobrr"
postgresPass = "s0meth!ng-l0ng-4nd-s3cure"
postgresSSLMode = "disable"
postgresExtraParams = ""

# Optional: connect via unix socket instead of host/port
#postgresSocket = "/run/postgresql"
```

Alternatively, the whole connection can be given as a single DSN, which takes precedence over the individual fields:

```toml title="config.toml"
databaseDSN = "postgresql://autobrr:s0meth!ng-l0ng-4nd-s3cure@localhost:5432/autobrr?sslmode=disable"
```

:::warning[Warning]
It's up to you to make sure your PostgreSQL instance is secured and not exposed to the internet.
:::

:::info[Advanced]
autobrr runs its database schema migrations automatically on startup. Set `databaseAutoMigrate = false` to skip them.
:::

## Convert from SQLite to PostgreSQL {/* #convert */}

`autobrrctl` has built-in support for converting your SQLite database to PostgreSQL.
To do so, shut down autobrr and issue the following command:

```bash
autobrrctl db:convert --sqlite-db /path/to/autobrr.db --postgres-url postgres://username:password@127.0.0.1:5432/autobrr
```

Two optional flags are available:

- `--dry-run`: test the conversion without writing anything to PostgreSQL.
- `--exclude-tables`: comma separated list of tables to skip during conversion.

Your SQLite database will not be removed in this process, so it is safe to roll back if you like.

Remember to update the autobrr configuration file before starting autobrr again.

---

## Transfer your installation


This guide will walk you through the steps needed to transfer your settings such as filters, indexers, IRC networks, feeds, clients, notifications and API keys of your current autobrr installation from one host to another.

:::info
Settings like hostname / IP, port, baseUrl, logPath or logLevel are not transferred and have to be adjusted again in `config.toml` after the transfer in case you made any changes to this file.
:::

## Backing up your current installation

First you need to stop the autobrr service on your old host so that we can safely pull the `autobrr.db`  
and to prevent any conflicts after restoring your installation on your new host.

All filters, indexers, IRC networks, feeds, clients, notifications and API keys are stored in this file.  
Stopping autobrr can be done in multiple ways depending on your setup or the hosting provider you use.  
Please refer to the documentation of your hosting provider for how to stop autobrr in case you don't know how to stop autobrr.

After you stopped your autobrr service, use the FTP program of your choice to connect to your old host and  
download the `autobrr.db` from `~/.config/autobrr`.

:::info
You may need to enable the option to show hidden files and folders in your FTP program (if not already enabled) since the `.config` folder will not be shown otherwise.
:::

## Installing autobrr

Now that you have successfully backed up your `autobrr.db` from your old host, you need to install a new instance of autobrr on your new host.

Please refer to our guides or to the guides of your hosting provider on how to install autobrr on you new host:

- [Linux](../linux.mdx)
- [macOS](../macos.mdx)
- [Windows](../windows.mdx)
- [Docker](../docker.mdx)
- [Shared Seedbox](../seedbox.mdx)

## Restoring your database

Having successfully installed autobrr on your new host we can now restore your `autobrr.db` backup.  
Stop autobrr on your new host and delete the following files (via SSH or FTP) if present:

- autobrr.db
- autobrr.db-shm
- autobrr.db-wal

After deleting these files you can upload the backup of your `autobrr.db`.

Once the upload is successfully completed you can start your autobrr service on your new host and  
you will be greeted with your restored stats, activity and settings from your old host!

:::info

Having restored the `autobrr.db` from your old host, your new installation will now have the password of the old autobrr installation!

:::

---

## Installation instructions for Windows

# Windows

In this setup we will create an autobrr user and a Windows service that operates in the background. This way we won't need to have a command prompt window open 24/7.

## Download package {/* #download-package */}

Download the latest Windows release and unpack. Place everything in `C:\autobrr` or some other directory.

Latest release can always be found at [Github](https://github.com/autobrr/autobrr/releases/latest).

### Manually configure autobrr (optional) {/* #manually-configure-autobrr */}

You can either let autobrr create the config itself at startup, or create one manually. For more information, please visit [configuring autobrr](../configuration/autobrr.mdx) which covers creating a user manually, configuring the default port, setting the desired log level, etc.

## Create Windows task {/* #create-windows-task */}

Press your Windows key and search for **Task Scheduler** and lets **Create basic task**.

Add a name, this will show up in the Task Scheduler. Feel free to add the autobrr description if you'd like:

> autobrr monitors IRC announce channels to get releases as soon as they are available with good filtering.

Next you'll set a **Trigger** which we want to start as soon as we **login to the computer**.

Our Action will be to **Start a Program** and we'll set our path to the autobrr.exe. Just click **Browse** and navigate to where you put your **autobrr.exe**

:::caution[Don't skip "Start in"]
Set **Start in (optional)** to the folder autobrr lives in, e.g. `C:\autobrr`. It is not actually optional for autobrr: without it, Windows starts the task in `C:\Windows\System32`, and autobrr creates and reads its `config.toml` and database **there** instead of in your autobrr folder. This is the most common cause of autobrr "losing" its settings or asking you to register again after a reboot.

Alternatively, put `--config C:\autobrr` in **Add arguments (optional)**, which points autobrr at the right folder no matter where the task starts.
:::

Our final step is to **Run whether user is logged on or not** After you set this it'll prompt you for the Windows Administrator password. Enter it and you should be ready to run.

And we're done, the scheduled task has been created (you'll find it in Task Scheduler, not in the Windows Services list). Now right click on autobrr in the list and click **Run.**

:::tip

If you ever need to restart the service, within Task Scheduler you can click on End and Run on the right side bar.

:::

## Reverse proxy (recommended) {/* #reverse-proxy-recommended */}

## Finishing up {/* #finishing-up */}

Now that autobrr is up and running, you should be able to visit your web UI at [http://localhost:7474](http://localhost:7474), `http://YOUR_LOCAL_IP:7474` or `http://domain.tld:7474` and proceed with your registration/login.

:::info
If the web UI asks you to register again after a restart, or your settings seem to be gone, the task is almost certainly running without **Start in** set; see [the caution above](#create-windows-task).
:::

---

## Introduction

With inspiration and ideas from tools like trackarr, autodl-irssi and flexget we built one tool that can do it all, and then some.

autobrr is the modern download automation tool for torrents.

## What is autobrr and how does it fit into the ecosystem? {/* #what-is-autobrr */}

We can start by talking about torrent trackers (hereby referred to as indexers) and maintaining ratio.
You are required to maintain a ratio with most indexers. Ratio is built by seeding your torrents.
The earlier you're seeding a torrent, the more peers you make yourself available to on that torrent.

Software like Radarr and Sonarr utilizes RSS to look for new torrents. RSS feeds are updated regularly, but too slow to let you be a part of what we call the initial swarm of a torrent. This is where autobrr comes into play.

Many indexers announce new torrents on their [IRC](./configuration/irc.mdx) channels the second it is uploaded to the site. autobrr monitors such channels in real time and grabs the torrent file as soon as it's uploaded based on certain conditions (hereby referred to as [filters](filters/intro.mdx)) that you set up within autobrr. It then sends that torrent file to a download client of your choice via an [action](./filters/actions.mdx) set within the filter. A download client can be anything from qBittorrent and Deluge, to Radarr and Sonarr, or a watch folder.

When your autobrr filter is set to send the torrent files to Radarr and Sonarr, they will decide if it's something they want, and then forward it to the torrent client they are set up with.

autobrr can also send matches (torrent files that meets your filter's criteria) directly to torrent clients like qBittorrent, Deluge, r(u)Torrent and Transmission. You don't need to use the \*arr suite to make use of autobrr.

### The typical workflow {/* #the-typical-workflow */}

1. autobrr monitors IRC channels and/or RSS feeds for new torrents that fits your criteria set within your autobrr [filters](filters/intro.mdx).
2. A successful match is forwarded to your [download client](./configuration/download-clients/dedicated) of choice via an [action](./filters/actions.mdx) set inside your filters.
3. If the download client is a torrent client, then the torrent client accepts the torrent file and starts downloading it.
4. If the download client is Radarr (or any other kind of \*arr), then Radarr will check that torrent file and see if it meets Radarr's criteria.

   Criteria like:

   - Is the movie monitored?
   - Is the torrent autobrr sent considered an upgrade of your existing version of that movie?

   Radarr will reject it if it doesn't meet its criteria.
   If Radarr accepts it, then it will forward it to its download client and handle the rest from here.

5. You are now among the very first people seeding this torrent which means you will have more peers connecting to you than if you'd be grabbing that file after the initial swarm. This results in a higher ratio on your indexers.

### RSS support for indexers without an IRC announcer {/* #rss-support-for-indexers-without-an-irc-announcer */}

A lot of indexers do not announce new torrents in an IRC channel. You can still make use of these indexers with autobrr since it has built in support for feeds as well. We support Torznab, Newznab, as well as regular RSS feeds.
RSS indexers are treated the same way as regular indexers within autobrr.

This isn't needed if your use case is feeding the \*arrs only. Since they have RSS support already.

## Features {/* #features */}

As of right now, autobrr features:

- Support for 100+ indexers with IRC announces
- RSS and Torznab/Newznab support via Prowlarr to easily get access to hundreds of indexers
- Powerful but simple filtering with RegEx support (like in autodl-irssi)
- Easy to use and mobile friendly web UI (with dark mode!) to manage everything
- Built on Go and React making autobrr lightweight and perfect for supporting multiple platforms (Linux, FreeBSD, Windows, macOS) on different architectures (e.g. x86, ARM)
- Great container support (Docker, k8s/Kubernetes)
- Database engine supporting both PostgreSQL and SQLite
- Notifications (Discord, Notifiarr, Telegram, Pushover, Gotify, ntfy, LunaSea, Shoutrrr, webhooks)
- Multi-language web UI (English, German, Czech, Spanish, French, Russian, Norwegian, Simplified Chinese)
- One autobrr instance can communicate with multiple clients (both torrent and \*arr) on remote servers
- Base path / Subfolder (and subdomain) support for convenient reverse-proxy support

Available download clients and actions

- qBittorrent (with built-in re-announce, categories, rules, max active downloads, etc.)
- Deluge v1+ and v2+
- rTorrent / ruTorrent
- Transmission
- Porla
- aria2
- Sabnzbd (Usenet)
- NZBGet (Usenet)
- Sonarr, Radarr, Lidarr, Readarr and Whisparr (pushes releases directly to them and gets in the early swarm, instead of getting them via RSS when it's already over)
- Watch folder
- Exec custom scripts
- Webhook

## About {/* #about */}

The development of autobrr started in Early 2020, entering rapid development in Summer 2021 due to dissatisfaction with needing 3+ tools to do one job. Autobrr has since gained quite a bit of traction and has a growing [community](./community.mdx) supporting the project.

Autobrr was developed with resource consumption in mind. The software uses API calls to reduce unnecessary downloads of .torrent files from sites like BTN, RED, PTP, and GGn. On other sites, it will download the .torrent only if the information is not present in the announce message.

### License {/* #license */}

autobrr is licensed under the GNU General Public License v2.0.

The GNU GPL is the most widely used free software license and has a strong copyleft requirement. When distributing derived works, the source code of the work must be made available under the same license. There are multiple variants of the GNU GPL, each with different requirements.

---

## Quick Start


The following considers a common use case, feeding IRC announcements for a private
tracker to a Servarr instance, as a way to illustrate how the components of autobrr fit
together and what is required to get up and running. It's not the only use case and
other use cases may require more RTFM'ing in [the configuration docs](./configuration/autobrr.mdx).

1. [Install autobrr](./installation/linux.mdx).

   Proceed once the web UI is accessible.

2. Create a user for yourself.

   Most easily done through the initial "GUI" in the web UI when autobrr is first
   started.

3. [Register a nick on your indexer's IRC
   network](/configuration/irc#registering-with-nickserv).

4. [Group a "bot" nick with your real nick](./configuration/irc.mdx#grouping-nicks).

   This is the common case, but check your tracker's IRC documentation and adjust as
   appropriate.

5. Add an [indexer](./configuration/indexers.mdx).

6. Add a [download client](./configuration/download-clients/dedicated).

   **NOTE**: In the context of autobrr, Servarr instances are considered download
   clients.

7. Add a [filter](filters/intro.mdx).

   To feed all IRC announcements to a Servarr instance to let it decide what, if
   anything, to do with the release, just add a filter with the indexer from #5
   selected and leave the rest blank. Don't forget to enable the filter.

   **NOTE**: Autobrr does nothing with received IRC announcements without at least one
   filter applied to at least one indexer.

8. Add a [filter action](./filters/actions.mdx).

   Add an action of the matching Servarr type (e.g. Sonarr type action for a Sonarr
   instance), select the "download client" that corresponds to that type from #6, give
   it a name and save.

   **NOTE**: Autobrr does nothing with received IRC announcements without at least one
   action enabled in at least one filter.

9. Double-check the resulting settings so far.

   Review all the indexer, download client, and IRC network settings in the autobrr web
   UI and correct any errors and omissions. Ensure that everything but the IRC network
   is enabled.

10. Enable the IRC network.

    **NOTE**: The network will display as `unhealthy` and `network unhealthy` messages
    appear in the logs until authentication has succeeded and autobrr has successfully
    joined the announcements channel. So you may safely ignore these messages until the
    logs show further information about connecting, authenticating and joining the
    channel.

Now you can monitor the logs for announcements from IRC, pushes to the Servarr instance,
and details for what, if anything, Servarr did with the release:

```
INFO Matched 'Foo Series S01E01 1080p WEB h264-BarGrp' (All) for foo-indexer
DEBUG release.store: &{ID:12 FilterStatus:FILTER_APPROVED Rejections:[] Indexer:foo-indexer FilterName:All Protocol:torrent Implementation:IRC Timestamp:1970-01-01 00:00:00.000000000 -0000 UTC m=+0000.000000000 GroupID: TorrentID:######### TorrentURL:https://www.example.com/Foo+Series+S01E01+1080p+WEB+h264-BarGrp.torrent TorrentTmpFile: TorrentDataRawBytes:[] TorrentHash: TorrentName:Foo Series S01E01 1080p WEB h264-BarGrp Size:0 Title:Foo Series Category:TV :: Episodes HD Categories:[] Season:1 Episode:1 Year:0 Resolution:1080p Source:WEB Codec:[H.264] Container: HDR:[] Audio:[] AudioChannels: Group:BarGrp Region: Language: Proper:false Repack:false Website: Artists: Type: LogScore:0 IsScene:false Origin: Tags:[] ReleaseTags: Freeleech:false FreeleechPercent:0 Bonus:[] Uploader:Anonymous PreTime: Other:[] RawCookie: AdditionalSizeCheckRequired:false FilterID:1 Filter:0x########## ActionStatus:[]}
DEBUG sonarr: release push rejected: Foo Series S01E01 1080p WEB h264-BarGrp, indexer foo-indexer to http://localhost:8989 reasons: '[Unknown Series]'
DEBUG release rejected: Unknown Series
```

---

## Support Development


autobrr is developed and maintained by volunteers. Your support helps us continue improving the project.

## Donations

- [GitHub Sponsors](https://github.com/sponsors/zze0s)
- [Buy Me a Coffee](https://buymeacoffee.com/ze0s)
- [Ko-Fi](https://ko-fi.com/theze0s)

### Cryptocurrency

#### Bitcoin (BTC)

#### Ethereum (ETH)

#### Litecoin (LTC)

#### Monero (XMR)

---

For other currencies or donation methods, [reach out on Discord](https://discord.autobrr.com/).

---

## Account

## Changing Username and Password

:::info[Heads up!]
You will have to log in again after saving any changes here.
:::

Changing username and password can be done separately or simultaneously.

![Account dashboard](/img/account-dashboard.png)

### Changing Username

1. Go to `Settings` and navigate to the `Account` section.
2. Fill in your new username in the `New Username` field.
3. Enter your current password in the `Current Password` field.
4. Click save.
5. Log in with your new username.

### Changing Password

1. Go to `Settings` and navigate to the `Account` section.
2. Fill in your new password in the `New Password` field.
3. Confirm your new password.
4. Enter your current password in the `Current Password` field.
5. Click save.
6. Log in with your new password.

---

## Search function

The Releases tab will show you every matched and rejected release.
You can search through this list by typing your query and/or with selected keywords.

## Supported keywords

`category`
`codec`
`episode`
`filter`
`group`
`hdr`
`resolution`
`season`
`source`
`title`
`type`
`year`

:::tip
There are a lot of different categories. A crowd sourced list can be found [here](../filters/categories.mdx).
This is not a complete list by any means, so if you want to add missing categories to our docs, read [this](../filters/categories.mdx#how-to-export-categories-from-autobrrdb).
:::

## Usage

As an example, if you want to search for all 1080p releases from the year 2022:

- `year:2022 resolution:1080p`

If you want to list all Dolby Vision releases by a certain group:

- `group:framestor hdr:DV`

If you want to list all 1080p releases with the keyword `Movie Title`:

- `Movie Title resolution:1080p`

If you want to list episode 3 of season 5 in `The Show`:

- `The Show season:05 episode:03`

If you want to list only movies or only episodes:

- `type:movie` or `type:episode`

## Retrying actions

Clicking the action status badge of a release opens its details, where each action has a **Retry** button that replays it against the download client. This works for any action status, including approved and pending ones, and is handy after fixing a download client or filter misconfiguration.

## Release history cleanup

Release history can be cleaned up under `Settings > Releases`:

- **Scheduled cleanup jobs**: Run automatically on a cron schedule and delete releases older than a set number of hours, optionally scoped to specific indexers and push statuses. Jobs can be enabled, edited and force-run from the same screen.
- **Delete release history**: A manual tool for one-off cleanups with the same filtering options.

:::caution
[Skip Duplicates](../filters/skip-duplicates.mdx) and [Smart Episode](../filters/tv-movies.mdx#smart-episode) both compare new releases against previously approved ones in the release history. Deleting `PUSH_APPROVED` history removes the data they rely on, so scope cleanups accordingly.
:::

---

## Tips

## Stop if disk is full {/* #stop-if-disk-is-full */}

You can make autobrr stop adding torrents to your download client whenever you're running low on space.

### Create the script {/* #create-the-script */}

```bash
touch ~/freespace.sh && chmod +x ~/freespace.sh
```

```bash
#!/bin/bash
set -e

reqSpace=100000000 # 100GB
SPACE=`df "$HOME/torrents" | awk 'END{print $4}'`
if [[ $SPACE -le reqSpace ]]
then
  #echo "not enough space"
  #echo "free $SPACE"
  exit 1
fi
#echo "got space"
#echo "free $SPACE"
exit 0
```

For Docker:

```shell
#!/bin/sh
set -e

reqSpace=250000000 # 250GB
SPACE=$(df "/torrents" | awk 'END{print $4}')
if [ "$SPACE" -le $reqSpace ]
then
  echo "not enough space"
  echo "free $SPACE"
  exit 1
fi
echo "got space"
echo "free $SPACE"
exit 0
```

If the script sees that there is enough space available, it will return exit code 0 and autobrr will push the torrent to the download client.

If free space falls below your limit, the script will return exit code 1 and autobrr will skip it.

:::tip

If you want autobrr to check the disk space of a remote server, then place the script above at the remote server and this one at the server autobrr runs on and call it from the autobrr filter like explained below:

```bash
#!/bin/bash
retcode=$(ssh user@domain "bash -s < ~/freespace.sh ; echo \$? " 2>/dev/null)
echo $retcode
```

:::

### Add it to your existing filter {/* #add-it-to-your-existing-filter */}

![External script](/img/free-space.png "External script explanation")

## Downloading log files {/* #download-logs */}

Log files can be listed and downloaded under `Settings > Logs`. Downloaded files are automatically sanitized: passkeys, API keys and IRC credentials are redacted, which makes them safe to share when asking for help on Discord or GitHub.

## Application settings {/* #application-settings */}

A few useful toggles live under `Settings > Application`:

- **Theme**: light, dark, or follow the system theme.
- **Language**: the web UI is available in several languages (English, German, Czech, Spanish, French, Russian, Norwegian and Simplified Chinese). Your browser language is detected automatically, and the choice is stored per browser.
- **Check for updates**: toggles the update check; when a new version is available, a notice with a link appears next to the version number.
- **WebUI debug mode**: extra debug output in the browser, only useful when troubleshooting the UI itself.

## Troubleshooting filters utilizing the autobrr.log file {/* #autobrr.log */}

The Logs page in the app itself is a good way to monitor new announces, but it cannot show old announces.

If you want to check why a filter is not grabbing anything without waiting for a new announce, you can do so with `tail`.

### Enable logging if you haven't already {/* #enable-logging */}

```toml title="~/.config/autobrr/config.toml"
# autobrr logs file
# If not defined, logs to stdout
#
# Optional
#
logPath = "log/autobrr.log"

# Log level
#
# Default: "DEBUG"
#
# Options: "ERROR", "DEBUG", "INFO", "WARN", "TRACE"
#
logLevel = "TRACE"
```

### Check previous announces {/* #check-previous-announces */}

```shell
# -n 100 will search the last 100 lines, you might have to increase this
# put the name of your filter inside the parentheses

tail -n 100 ~/.config/autobrr/logs/autobrr.log | grep 'CheckFilter: (NAME OF YOUR FILTER)'
```

### Monitor new announces {/* #monitor-new-announces */}

```shell
# put the name of your filter inside the parentheses

tail -f ~/.config/autobrr/logs/autobrr.log | grep 'CheckFilter: (NAME OF YOUR FILTER)'
```

#### Expected output {/* #expected-output */}

```js
{"level":"debug","module":"filter","time":"2023-01-11T17:05:44Z","message":"filter.Service.CheckFilter: (Race - groups) for release: Teppen.Laughing.til.You.Cry.S01.720p.CR.WEB-DL.REPACK.AAC2.0.H.264-SubsPlease <Highlight color="#ff2754">rejections: (episodes not matching. got: 0 want: 1-99, release groups not matching. got: SubsPlease want: ggez,glhf,DiRT,cinefeel,casstudio,cmrg,flux,smurf,ntb,kings,plzproper,gossip,playweb,cakes,bae,ggwp,rapidcows,trollhd,playhd,playtv,truffle)"}
```

Based on the output here, the announce was rejected because you've blocked season packs by asking for episodes 1 to 99.
It was also rejected because the release group did not match your criteria.