Agregarr, a Plex collections manager that refreshes Home on a schedule

What Agregarr does to a Plex Home screen

Agregarr manages the collections that appear in Plex. A collection is a named row of titles, and Plex normally keeps whatever you add by hand until you remove it. Agregarr takes over that maintenance: it pulls lists from outside sources, matches their entries against the library, and rebuilds the collection contents on a schedule so the row reflects the source rather than the last time someone edited it.

The sources are broad and worth reading closely, because they split into two different kinds of data. External lists come from Trakt, IMDb, TMDB, Letterboxd, MDBList, FlixPatrol (Networks Top 10), AniList and MyAnimeList, each with presets or custom list options. Internal ones come from your own server: Tautulli statistics for the most popular content, and Overseerr requests, either per user or pooled as all requests. That second group is what makes the tool more than a list importer, since a request row is a record of what someone actually asked to watch.

Two other features shape the visible result. Collections can be reordered independently on the Home and Recommended screens and on the Library tab, so the same set of rows can be ordered differently in different places. And a randomise option rotates the order of collections on the home screen on its own separate schedule, which exists so the front page does not look identical on every visit.

Missing items are grabbed through the *arr stack, not by Agregarr

The critical design choice is that Agregarr does not download anything itself. It identifies titles that a list wants and the library does not have, then hands them to another service. Two paths exist: direct add through Radarr or Sonarr, or as a request through Overseerr. The distinction matters for permissions and for behaviour. A direct add goes straight into the automated download pipeline, while an Overseerr request goes through the request system, so the two paths behave differently depending on which you configure.

The filtering available at that point is what stops a list of four hundred titles from emptying your disk. Filters cover release year, season count, list position, genre and origin country, which between them let you say that you only want recent seasons, or only the top of a ranked list, or only content from a particular country. Position filtering is the useful one for top-ten style sources, where the tail of the list is rarely what you meant to import.

There is also a manual path, through a preview of the collection that shows the matching and missing items. From that preview you can add individual items via Radarr or Sonarr or Overseerr, or push items onto a global exclusions list, so a title the preview flags as a false positive stays excluded afterwards.

Coming Soon rows and the media mounts they require

The Coming Soon feature builds a collection out of things that do not exist yet, either from monitored content already known to Radarr or Sonarr, or from anticipated releases listed on Trakt, with trailers and poster overlays attached. The overlay is where the configuration gets specific: the release date and countdown drawn onto the poster depend on the container clock, so the compose example sets a timezone environment variable and points to the tz database list for finding the right identifier. The default in the example is Pacific/Auckland, and the README notes the value is set to your local timezone for accurate poster overlay release dates and countdowns.

This feature also has a hard infrastructure requirement that the rest of the application does not have. It needs media volumes mounted into the container so placeholder files can be created for unreleased titles, and the README is explicit that these folders should be added to Plex but not added to Radarr or Sonarr, otherwise the placeholders compete with the real releases. The compose example mounts separate movie and tv placeholder directories, and the application then wants you to select your root folders under Settings to Downloads.

Without the mounts, the README says Agregarr can run remotely and all other features work normally. That is a reasonable fallback, but it means the Coming Soon row and the poster overlay are unavailable, so the timezone variable matters only in the configuration where the volumes are present.

A Node and Next.js application behind a single container

The stack is a TypeScript application with a Next.js frontend and a server directory, and the repository layout shows a split between the two: src/ holds the client, server/ holds the backend, and agregarr-api.yml sits at the top level as the API description. The package.json scripts confirm the shape of the build, with separate build:next and build:server steps that a combined build script runs in order, and a start script that launches the compiled server entry point. TypeORM appears in the migration scripts, so the application persists state in a database it manages itself.

The Dockerfile builds on node:20.19.5-alpine in two stages. The first stage installs the build toolchain, including cairo, pango, jpeg, giflib and pixman development packages, then runs the full build and strips the dev dependencies in a second install pass. The runtime stage keeps the same Alpine base and adds ffmpeg, python3, tzdata and tini, and it downloads a set of poster fonts into /usr/share/fonts/truetype/poster-fonts. Those fonts are the mechanism behind the poster template feature, which lets you build your own poster designs that get filled dynamically with content on a per collection basis.

Because everything ships in one image, deployment is a single container, but the image is not small. It carries a full media toolchain, a font set, an ffmpeg binary and a second copy of the application for the Next.js frontend.

Config directory, port 7171, and a volume that must be right

The compose file in the repository root is the developer variant, and it is worth reading next to the published example because it shows what the image expects. It builds from a local Dockerfile.local, mounts the working directory at /app, and maps the same port 7171 on the host. The published example in the README is the one aimed at users, and it pulls the agregarr/agregarr:latest image instead.

The critical setting is the volume. The README warns that your volume must be set correctly for your settings to persist, and that if Agregarr resets after a restart it is because the volume is not set correctly. That is a hard failure mode worth internalising before anything else, because a container that loses its state on every restart looks like a broken app rather than a misconfigured mount.

The published example is short enough to reproduce, and every value in it comes straight from the README:

services:
  agregarr:
    image: agregarr/agregarr:latest
    container_name: agregarr
    volumes:
      - /path/to/config:/app/config
    ports:
      - 7171:7171
    restart: unless-stopped

The two paths in the volume line are the placeholder the README tells you to replace with your own, and the commented examples in the README show the Linux and macOS form pointing at a server data directory and the Windows form using a drive letter. The application then answers at `http://localhost:7171` once it is up. Basic setup instructions live at agregarr.org/docs/installation, with the placeholder volume instructions on a separate page, and the compose file is where the TZ variable and the optional placeholder mounts belong.

Sync schedules, time windows and per collection overrides

Agregarr updates collections on every sync, and the default interval is 12 hours, with custom scheduling available at the application level and further custom sync options per collection. There is a second, separate schedule for the randomise home order behaviour, so the shuffle can rotate on a different rhythm from the content refresh rather than tying both to one timer.

Time restrictions sit alongside the schedule. A collection can be active only during specific time periods, which is how a seasonal or promotional row appears and disappears on its own. Combined with independent reordering across the Home and Recommended screens and the Library tab, the model is per collection control over three axes: what is in the row, when the row is visible, and where the row sits.

The template system handles naming, with flexible templating and title importing from lists, so a row can carry a name that changes as the list changes without you editing it by hand. Existing collection integration extends the same control to collections you created elsewhere: any pre-existing collections in Plex and the default hubs such as Recently Added can be managed alongside Agregarr managed ones. The collection statistics dashboard then reports the most popular collections using Tautulli data and the recently added missing items.

Where Agregarr is the wrong tool, and what it sits next to

The clearest limitation is that Agregarr is not standalone. It sits inside a Plex deployment that already has a media acquisition path, and it needs write access to modify collections on the server. A Plex installation with no Radarr, no Sonarr and no Overseerr gives the tool nothing to do with the missing items it finds, and the Coming Soon feature additionally demands mounted media directories, Plex root folders for them, and a correct TZ value for the poster countdowns to be right. The README states the project is licensed GPL-3.0, and the LICENSE file in the repository root carries the terms, which matters if you plan to modify and redistribute the code rather than just run it.

For alternatives, the README names its own lineage. Agregarr was originally built off Overseerr. It is also inspired by Kometa, and the credits go further, listing Coming Soon code references from UMTK and the anime ID mappings file from PlexAniBridge. The difference in approach between the two named references sits in the configuration surface. Overseerr is the code base Agregarr grew out of, and the visible result is a web application configured through a browser interface on port 7171, with settings, per collection filters, template editing and a statistics dashboard all living in that interface. The Kometa relationship is described only as inspiration, and the README does not document how Kometa itself is configured, so the useful contrast stops at the level of surface: Agregarr is a UI driven service that persists to a mounted config directory, and its own documentation, not a configuration file, is where you go to set a sync interval or a poster template.

Editorial conclusion

Agregarr fits Plex administrators who want Home and Recommended to reflect list membership, Overseerr requests or Tautulli watch data without hand-editing rows, and who are already running Plex alongside Radarr, Sonarr or Overseerr. It does not fit anyone looking for a general Plex plugin, since it mutates collections and needs write access to the server, and it does not fit a library where media cannot be added automatically, because the grab behavior is the point of the tool. Before deploying it, verify the version of Plex you run accepts programmatic collection edits, confirm the config volume is mounted at /app/config so settings survive a restart, and read the release notes for v2.4.2, the most recent tag dated 2026-03-17, against the last push of 2026-04-23.

Frequently asked questions

Official sources

1. agregarr/agregarr on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases