# Configarr: syncing TRaSH Guides into Sonarr and Radarr

> Configarr is a TypeScript tool that pulls custom formats and quality profiles from the TRaSH Guides into Sonarr, Radarr and other *arr applications, with a defined merge order and support for your own custom formats. It suits self-hosted media library operators, and it is only partly usable on the experimental applications.

**raydak-labs/configarr** — Sync TRaSH Guides + custom configs with Sonarr/Radarr

- Repository: https://github.com/raydak-labs/configarr
- Website: https://configarr.de/
- Stars: 672 · Forks: 30
- Language: TypeScript
- License: AGPL-3.0
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/raydak-labs-configarr

## Custom formats drift apart unless something reconciles them

Every Sonarr or Radarr instance carries a set of custom formats, and those objects decide which release of a file gets grabbed. Custom formats drift, because you add one by hand on one instance, another one arrives with a different name on the second instance, and the quality profile that references them no longer matches. The result is a library where the same movie is grabbed in wildly different qualities depending on which instance handles it.

Configarr is the tool that reconciles that. It is described as an open-source tool for simplifying configuration and synchronisation for Sonarr and Radarr, and it integrates with the TRaSH Guides to automate updates of custom formats, quality profiles and other settings, while also supporting user-defined configuration. The topic tags place it in the wider *arr ecosystem alongside servarr, sonarr, radarr, lidarr, readarr, whisparr, notifiarr and recyclarr.

The problem it takes on is not the *arr applications themselves. Those have an API and Configarr talks to it. The problem is the configuration objects, which are numerous, interdependent and slow to set up by hand, and which have to be pushed into every instance you operate.

The comparison in the README is instructive. The project says it will be similar to Recyclarr or Notifiarr, but with support for additional specification and not only what TRaSH-Guides offer. The related projects section adds Dictionarry-Hub/profilarr, and the documentation site hosts a feature comparison page across those tools. So the project positions itself in a crowded niche on the basis of breadth: more configuration surfaces, not just custom formats.

## Four ways to supply custom formats and one merge order

The feature list in the README is where the actual behaviour lives. Custom formats can come from four places, and the order between them is fixed and stated: the merge order is TRaSH-Guides, then LocalFiles, then CFs in Config, with later sources overriding earlier ones.

That ordering is the single most important thing to understand before you write a configuration. A custom format that TRaSH Guides defines can be overridden by one in a local file, and both can be overridden by one you write directly into the configuration. If you are wondering why your instance does not behave the way the guide describes, the answer is usually that a later source in that chain is winning.

The four sources are: syncing from TRaSH-Guides, syncing with local file custom formats, providing custom formats directly in the configuration, and the reusable custom formats that ship with the project itself under custom/cfs/. The README notes that those bundled formats are ones TRaSH-Guides does not offer, and that most come from PCJones, pointing at the radarr-sonarr-german-dual-language and usenet-guide projects. The German guide is called out as a good one, which tells you the audience includes non-English libraries.

Two other capabilities belong in the same picture. Configarr is stated to be compatible with Recyclarr templates, which means teams that already have template-based configuration are not forced to rewrite it. And it supports all CustomFormat specifications, with the ability to define custom formats for different languages and countries.

The documentation also points to a JSON to YAML converter for people who want to paste formats directly into the configuration file rather than write YAML by hand.

## Secrets stay out of the configuration file

The configuration is a YAML file called config.yml, created from a template in the repository, and the README shows it supports three custom tags for values.

The first is a secret tag, written as value: !secret secretKey, which loads the value from the secrets file under that key. The second is an environment tag, value: !env ENV_NAME, which reads an environment variable. The third is a file tag, value: !file FILE_NAME, which reads the value from a file, with a note that Configarr needs enough permissions to read it.

This matters more in Configarr than in a typical YAML tool, because the values in a *arr configuration are API keys. The secrets file is a separate file, created from a secrets.yml template, which keeps the key out of the file you would put in version control.

The tag design is worth a second look because it is a preprocessing step rather than a YAML feature. A plain YAML parser would reject the !secret tag, so Configarr resolves these tags before or during parsing, and the values it substitutes come from three different places with different lifecycles. The file variant in particular is the one for mounted Docker secrets, where a Kubernetes deployment can expose a file and a local run can point at a path.

The configuration documentation is linked separately, and the README notes that it covers Sonarr v5-only settings, which is where the difference between a v4 instance and a v5 instance becomes visible.

## A first run against a local Sonarr and Radarr

The development section of the README is the closest thing to a tutorial, and it is written for someone running a local instance to test against.

The first step is optional but sensible: run docker compose up -d to bring up a container, then open Sonarr in a browser at http://localhost:8989 or Radarr at http://localhost:7878. You configure basic authentication, disable local authentication, and create an initial user with an email address and a password. The reason to disable local authentication is that the tool authenticates with the API key instead, and the next step is to open the Sonarr Settings and General page and copy the API key.

The second and third steps are file operations. You create a secrets.yml from the template with cp secrets.yml.template secrets.yml and replace the placeholder with the API key, and you create a config.yml with cp config.yml.template config.yml, overwriting the hosts if you are not using the local docker compose setup.

The final step is to run the application with pnpm start, or through the VS Code task. The README also points at the full example and at using the container with a mounted src directory as alternatives.

The package.json shows the development commands behind that workflow, and the start script is worth noting because it runs the TypeScript sources directly rather than a built bundle:

```json
  "name": "configarr",
  "type": "module",
  "scripts": {
    "build": "tsx esbuild.ts",
    "start": "tsx src/index.ts",
    "test": "vitest run",
```

So a first run needs a Node environment, pnpm, and a reachable *arr instance with an API key. The Docker images are the alternative for people who would rather not set up a development environment, and the README gives the image references for both registries.

## Which *arr applications are covered, and how Sonarr v5 is detected

Support levels are stated precisely, and the distinction between supported and experimental is the one to carry into a deployment decision.

Radarr v5 and above is supported. Sonarr v4 and the Sonarr v5 beta are supported, with the caveat that v5-only settings require a v5 instance. Whisparr, Readarr and Lidarr are all listed as experimental.

The Sonarr version handling is the interesting engineering detail. The README states that Sonarr API versions are detected at runtime, so existing v4 configurations continue to work. That is a compatibility decision rather than a convenience: an operator with a mixed fleet does not have to maintain two configuration files or convert anything when an instance moves from v4 to v5.

The cost of that flexibility is that a configuration can contain a v5-only setting and still be loaded against a v4 instance, in which case the setting has no meaning. The README addresses this by pointing to the configuration documentation for the Sonarr v5-only settings, which is where you find out which keys are safe to share across both versions. That is a documentation dependency, not a validation guarantee, and a mixed fleet means you have to read that page rather than assume the tool will warn you.

The project also describes itself as ensuring compatibility with the latest versions of Sonarr and Radarr, and as a tool that saves time, enhances consistency and reduces manual intervention. The consistency claim is the one that matters for an operator, since a single source of truth for custom formats across instances is the whole point.

## Container build, pnpm workspace and the shipped image

The repository is a pnpm workspace with packages under pkgs/, sources in src/, and separate documentation, examples, scripts and tests directories. The examples folder has a full/ and a scheduled/ example, which suggests the intended way to run the tool is as a scheduled job rather than a long-running daemon.

The Dockerfile is a multi-stage build on Node 24, with pnpm activated through corepack:

```dockerfile
FROM node:24.20.0-slim AS base
WORKDIR /app
ENV PNPM_HOME="/opt/pnpm"
ENV COREPACK_HOME="/opt/corepack"
ENV PATH="$PNPM_HOME:$PATH"
```

The build stage compiles the TypeScript with the esbuild script, and the production stage copies the bundle out of the builder:

```dockerfile
COPY --from=builder /app/bundle.cjs /app/index.js
```

Two details in the production stage are there for a reason. The image installs dumb-init and uses it to run Node, so Node is not PID 1 and signals are handled properly, which is what a scheduled job in Kubernetes needs. And it sets the git safe.directory configuration globally, with a comment referencing issues 240 and 241, so that git operations inside the container work regardless of the container user and the directory owner on the host.

Published images are available from GitHub Container Registry as ghcr.io/raydak-labs/configarr:latest and from Docker Hub as configarr/configarr:latest, each with tagged versions alongside the latest tag.

The build is also parameterised, with build arguments for CONFIGARR_VERSION, BUILD_TIME and the GitHub run identifiers, which means the running container can report which build it came from. That is a small feature with real value in a scheduled job, where the version that ran is often the first question asked when a sync goes wrong.

## Two licences, a release pipeline and a real end to end test suite

The licence is AGPL-3.0 according to the project metadata, with a LICENSE file at the root of the repository and a GitHub licence badge in the README pointing at it. The package.json, however, records the license field as ISC. That mismatch is a real thing an integrator has to resolve before redistributing anything, and it is not something this article can interpret for you, only point at. The README excerpt carries no licence section of its own, so a project with two different licence signals in two places needs a human to settle which one governs.

The release process is automated with release-it and the conventional-changelog plugin, and the release numbers move quickly: 1.34.0 on 2026-10-03, 1.34.1 on 2026-10-08, and 1.35.0 on 2026-10-13, with the last push to the repository on 2026-10-14.

Testing is where this project looks most serious, and the package.json scripts show it. Unit tests run on vitest, and there are three separate end to end suites for the *arr applications: a parallel suite, a pipeline suite, and a dedicated Sonarr v5 suite that points at its own base URL and API key through environment variables with defaults. The configuration files for those runs sit at the root of the repository as vitest.arr-e2e.config.ts and its siblings, and playwright is in the dev dependencies alongside the swagger-typescript-api generator used by the generateApi script, which points at the *arr API definitions.

Generating the API client from the schemas rather than hand-writing it is what keeps a tool like this working across Sonarr v4 and v5. The cost is that the generated client and the endpoint behaviour have to be regenerated when the applications change, which is part of the upgrade work you inherit when you adopt it.

## Conclusion

Adopt Configarr if you run Sonarr or Radarr across several instances and want custom formats and quality profiles kept in step with the TRaSH Guides, and you can accept a configuration file as the source of truth. Do not adopt it expecting the experimental applications to be equally supported, since Whisparr, Readarr and Lidarr are marked experimental, and do not rely on it to manage anything other than the *arr configuration surface. Verify first that your Sonarr major version is detected as expected at runtime, that your own custom formats are placed in the right position in the merge order, and that the licence question is settled for your deployment, since the repository is AGPL-3.0 while the package.json records ISC, and the last push was on 2026-10-14 with release 1.35.0 dated 2026-10-13.

## FAQ

### What does Configarr sync into Sonarr and Radarr?

It integrates with the TRaSH Guides to automate updates of custom formats, quality profiles and other settings, and it also supports user-defined configuration and custom formats that TRaSH-Guides does not offer, which ship under custom/cfs/ in the repository.

### In what order does Configarr merge custom formats?

The README states the merge order is TRaSH-Guides, then LocalFiles, then custom formats provided in the config, so later sources override earlier ones. It is also compatible with Recyclarr templates.

### How do I keep the Sonarr API key out of my Configarr configuration?

You create a secrets.yml from the template, place the API key there, and reference it from config.yml with the custom tag value: !secret secretKey. Values can also come from an environment variable with !env or from a file with !file.

### Which *arr applications does Configarr support today?

Radarr v5 and above, and Sonarr v4 and the v5 beta are supported, with v5-only settings requiring a v5 instance, and Sonarr API versions are detected at runtime. Whisparr, Readarr and Lidarr are listed as experimental.

## Sources

- [License: AGPL-3.0](https://github.com/raydak-labs/configarr/blob/main/LICENSE)
- [Project website](https://configarr.de/)
- [raydak-labs/configarr on GitHub](https://github.com/raydak-labs/configarr)
- [README](https://github.com/raydak-labs/configarr/blob/main/README.md)
- [Releases](https://github.com/raydak-labs/configarr/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/raydak-labs-configarr