Get started

Up and running in three steps

Kustos runs on the machine your library already lives on, and stays on your own network. Nothing to configure by hand before you can look around.

1

Sign in with Plex

Use the Plex account that owns your server — that account becomes the admin, and from then on it is the only one that can sign in. Everyone else links to it by invite.

2

Start the trial

Press Start free trial. The 30-day trial needs no card, and nothing is maintained until it has started.

3

Let it find the rest

Kustos looks for Sonarr, Radarr, Tautulli and the others already running on the same machine and offers them, so you rarely type an address.

One operator

Invite links connect accounts, not people

Kustos is a single-operator app. An invite link is a one-page form where someone links their own Trakt account — it gives them no login and no access. For someone outside your home network to open it, Kustos needs an address they can reach: set External URL in Settings → General (a reverse proxy, tunnel or Tailscale name). Without one the link only works on your own network.

  • —One page, one action: they link their Trakt account. There is no Kustos account, no login and nothing they can see or change.
  • —Once linked, their watchlist turns into requests you approve.
  • —Their plays join the merged watch history that protects what they are watching.
  • —Reading plays from your Plex server needs no link at all — this is only for their own watchlist and their own Trakt history.
Invite someone

The link works once, for them, and expires after 7 days. Making a new link for the same person replaces the old one.

Keys worth having

What to connect, and where each key comes from

Kustos works the moment Plex is connected. Everything below adds something — none of it is required, and you can add any of it later from Connections.

Your own apps

Already running alongside Plex. Kustos finds these and asks for their key, which each one shows in its own settings.

  • PlexRequired

    Sign in with the account that owns the server — no key to copy.

  • Sonarr / RadarrStrongly recommended

    Settings → General → API Key in each. Several instances are fine.

  • ProwlarrOptional

    Same place: Settings → General → API Key.

  • TautulliRecommended

    Settings → Web Interface → API key. This is what gives you episode-by-episode watch detail.

  • Overseerr / JellyseerrOptional

    Settings → General → API Key, if the house requests through one.

Metadata & artwork

All free to sign up for, and all on your own accounts — every lookup is made by your machine with your own key, under the terms you agreed to. Kustos only adds its own app id where a service asks for one. Each one fills in something different, and nothing breaks without them.

  • TMDBRecommended

    Free account at themoviedb.org → Settings → API. Powers most metadata, ratings and collection sources.

  • MDBListRecommended

    Free account at mdblist.com → Preferences. Rating badges and list-driven collections come through it; the free tier fills a big library in over a couple of weeks.

  • Fanart.tvOptional

    Free account at fanart.tv → your API page. Logos and extra artwork.

  • TheTVDBOptional

    Free key from thetvdb.com/api-information. Helps where TMDB and TVDB disagree about a series.

Watch data

Account links rather than keys. More sources means a missed play never costs someone their progress.

  • TraktRecommended

    Connect the account from Connections — one click, then approve it on trakt.tv.

  • SimklOptional

    Same again: connect and approve.

  • Plex historyIncluded

    Already there. Turn it on in Plex if you want per-episode plays without Tautulli.

AI

Three separate keys on purpose, so artwork checking can never spend the quota your suggestions need. You can add several keys per card and Kustos moves to the next when one runs dry.

  • AI HelperRecommended

    The assistant that builds collections and rules for you. Free key from aistudio.google.com/apikey.

  • Suggestions AIOptional

    One call per person per day — a free key covers it comfortably.

  • Gemini VisionOptional

    Finds text baked into posters across the whole library. It is thousands of calls, so add a few free keys from separate projects and Kustos works down the list — that is how a large library gets through it.

Nothing here is asked for twice — paste a key once and Kustos remembers which jobs use it.
kustos · your server
Connections: every service Kustos talks to and whether it answered
Connections: everything Kustos talks to, and whether it answered.