Cantinarr

┌──────────────────────────────────────────────────────────────┐
│  Cantinarr Server (Go, single container, port 8585)          │
│                                                              │
│  ┌──────────┐ ┌───────────┐ ┌─────────┐ ┌────────────────┐   │
│  │ Auth/JWT │ │ Requests  │ │ Issues +│ │ AI Chat        │   │
│  │ Passkeys │ │+ Approvals│ │ AI Agent│ │ + 41 AI Tools  │   │
│  └──────────┘ └─────┬─────┘ └─────────┘ └────────────────┘   │
│                     │                                        │
│  ┌──────────────────┴───────────────────┐  ┌──────────────┐  │
│  │  ID Bridge: TMDB → Trakt → TVDB      │  │ TMDB/Trakt   │  │
│  │  (cached 30 days)                    │  │ discovery    │  │
│  └───┬──────────┬──────────┬──────────┬──┘  └──────────────┘ │
│      │          │          │          │                      │
│  ┌───┴───┐ ┌────┴───┐ ┌────┴─────┐ ┌──┴───┐ ┌────────────┐   │
│  │Radarr │ │ Sonarr │ │ Chaptarr │ │Lidarr│ │Flutter Web │   │
│  └───┬───┘ └────┬───┘ └────┬─────┘ └──┬───┘ │ (embedded) │   │
│      │          │          │          │     └────────────┘   │
└──────┼──────────┼──────────┼──────────┼──────────────────────┘
       │          │          │          │   ▲ webhooks push
  ┌────▼───┐ ┌────▼───┐ ┌────▼─────┐ ┌──▼───┐  external changes
  │ Radarr │ │ Sonarr │ │ Chaptarr │ │Lidarr│  back instantly
  └────────┘ └────────┘ └──────────┘ └──────┘  (+ SABnzbd,
                                      qBittorrent, NZBGet,
                                      Transmission, Deluge,
                                      ruTorrent, Tautulli,
                                      Tracearr, push gateway)

┌───────────────────────────────┐
│  Cantinarr App (Flutter)      │      ┌─────────────────────┐
│  Discovery, Requests, Books,  │─────>│  Cantinarr Backend  │
│  Music, Arr control, Issues,  │ REST │  (the only API the  │
│  AI, Push notifications       │ + WS │   app talks to)     │
└───────────────────────────────┘      └─────────────────────┘

Why Cantinarr?

• Zero-config requesting -- Your users never see API keys, TVDB IDs, or quality profiles. They browse, they tap, it works.
• TMDB + Trakt for movie and TV discovery -- The best metadata, images, and trending data, proxied through the server so keys stay off devices -- and TMDB works out of the box on a built-in key, no signup needed. Sonarr's TVDB dependency is invisible. Every discovery row keeps loading and opens into a full grid, and a Browse page filters by genre, release year, and rating.
• You choose what "popular" means -- The headline row on the Movies and TV tabs reads TMDB weekly trending, or Trakt trending (ranked by who is actually watching), or TMDB's all-time popularity ranking. Connect Trakt and the rows switch to it automatically -- no second setting to find. An English-only switch keeps movie and TV discovery and recommendation rows to English-language originals; it ships on, and search always finds everything either way.
• Automatic ID bridging -- TMDB-to-TVDB translation with Trakt fallback. The #1 source of failed Sonarr adds, solved.
• Browse before setup -- Admins start with Movies, TV Shows, Releases, Books, and Music. Explore catalogs and open details before connecting a service. Each unconfigured catalog has a fixed Set up Radarr/Sonarr/Chaptarr/Lidarr and Hide this tab footer; setup returns to the same catalog or title. Hiding affects everyone on the server, and the tab returns automatically when its service is configured, even if that service is offline. Restore or change these choices under Settings > Modules > Discover > Discover tabs. Releases hides only when Movies, TV Shows, and Music are all hidden; an empty schedule does not hide it. Library rows, availability, and service-catalog search appear once the service is connected; requester and kids access still follows existing grants. Only visible book/music opening rows load in the background.
• Books too -- Search the selected Chaptarr library, then tap eBook, Audiobook, or Request both. The exact native book, library, and search term stay attached to the request. A tap saves and acknowledges immediately; delivery, approvals, and retries continue in the background. The Books tab keeps Recently Added, Authors, and Series, with live format availability. Books use Chaptarr directly; Open Library discovery and matching have retired. Requester access is granted per user. Book links can still open the provider pages recorded by Chaptarr.
• Music too -- One search for albums, EPs, singles, and artists, with live Lidarr status and saved requests attached by MusicBrainz ID. Albums appear as soon as they return; artists load independently below them. Search, discovery, artist discographies, and library navigation open the same album page and one request control. A tap saves immediately, while approvals and delivery continue in the background. Only the selected release is monitored. Popular Albums, New Releases, and genres stay focused on albums and EPs, followed by Recently Added and Artists. Music needs a per-user Lidarr grant for requesters; admins can browse before setup. See music setup.
• Take available files with you -- Optional, resumable downloads let signed-in users save exact ebook, audiobook, movie, and episode files from their authorized library. Cantinarr re-checks the live arr file record before issuing a short-lived, file-scoped link without putting arr credentials in the URL.
• Requests survive catalog outages -- Book and album requests save before delivery and retry temporary failures after a restart. Approval and delivery progress stay separate; each book format has its own progress. Match an uncertain book on its detail page, retry a request that needs attention, or cancel it without discarding other people's shared requests.
• Request approvals -- Optional approval queue, globally or per user. Admins also control per-user season choice, quality choice, and default quality profiles. Approve/deny lands as a push notification for the requester.
• Kids accounts -- Mark a user as a child and set what they can see: the highest movie and TV rating for your region, whether unrated titles show at all, and whole genres to hide. The server does the filtering for that account everywhere a title can appear -- the discovery rows from TMDB and Trakt, search, title pages, people, the library rows, the AI assistant, and push alerts -- so nothing is trusted to the device, a rating that cannot be read hides the title rather than showing it, and requests from a kids account start out needing approval. Their own Settings say it in plain words: Kids account, movies up to PG, shows up to TV-PG. Books and music carry no ratings and stay grant-only per user, so grant those to a child on purpose.
• AI assistant -- "What should I watch tonight?" Every user can bring a personal Anthropic, OpenAI, Gemini, or xAI Grok API key, or link a subscription account with a one-time browser code -- OpenAI (OAuth) through ChatGPT, or xAI Grok (OAuth) through SuperGrok / X Premium+ -- even without included access, and their choice never has to match the server's provider. Admins can configure the same providers as an included server profile and grant that shared access per user. A personal provider is an explicit override; Cantinarr never silently spends the shared account when that override needs attention. The assistant searches your library, checks availability, requests for you, and gives admins conversational queue and release control.
• Local AI -- A first-class Local (OpenAI-compatible) provider runs shared AI against your own server (llama.cpp, vLLM, Ollama): enter a base URL and model ID, pin a reasoning effort, and skip the API key entirely (most local servers ignore auth; an optional token slot covers proxies that don't). Assistant traffic never leaves your network, and the save-time test proves the endpoint before anything is stored.
• AI remediation agent -- Users tap "Report a problem" (or Cantinarr detects one itself, in the queue or as it imports); each report is bound to the exact Radarr/Sonarr instance and begins with a quiet observation window. Cantinarr gives Sonarr/Radarr time to retry or replace a download before it alerts anyone or starts the agent; a persistent quiet problem then enters the supervised workflow. Recovery cancels stale proposals before dispatch. Automatic resolution requires an exact changed file plus a matching post-incident import record—not queue disappearance or a file that was already there. One whole class of this never needs reporting. The moment Sonarr says it imported an episode that has not aired yet, Cantinarr checks that season against its own air dates: a file your service imported before that episode aired cannot be that episode, and a season already holding files for episodes that have not aired is content that does not exist yet. When that is what happened, the season is already waiting in your issues with a fix attached — one issue for the whole season however many bogus files arrived, and an instance with no instant updates configured gets the same check on a quarter-hour timer instead. One approval fixes it: the agent proposes deleting exactly those files, blocklisting the releases that delivered them, and searching for replacements — only the episodes that have actually aired, leaving the rest of the season for your service to grab as it comes out. One problem, one decision; you are never asked to approve the second half of a fix you already approved. When the fix lands on something you reported, you are the one who says whether it worked -- "This is fixed" closes your own report, so an admin is never asked to adjudicate content they haven't watched. Tired of approving the same fix? Checking "Always approve" on an approval arms a standing rule for that exact problem-and-fix pair (force imports and destructive queue actions stay separate opt-ins): future matches are approved and executed without paging you, and the rule pauses itself the moment a fix fails or an issue closes out unresolved. Some problems should not be repaired again. When the same fault keeps coming back on one service -- on separate days, not just across a dozen titles in one bad minute -- Cantinarr says so once and names the setting that would stop it: the free-space floor, the remote path mapping, the indexer whose torrents have no seeders behind them. That is advice and never an edit; Cantinarr changes no setting on your services. Closing the notice is what mutes it -- for a couple of months if you fixed it, for a year if you told Cantinarr you are not going to -- and it only ever comes back if the problem does. Where there is no honest answer to give, nothing is raised at all. Remediation is server-owned: it always uses the admin's shared API key or shared OAuth connection (OpenAI or xAI Grok) and never a reporter's personal provider or per-user included-access grant. Admins may give remediation its own tested model designation while keeping that global provider and credential.
• MCP server -- 40 of the 41 in-app AI tools are exposed as a Model Context Protocol endpoint at /mcp, with OAuth discovery, browser/passkey login, dynamic client registration, and persistent rotating refresh tokens. Only the quality-profile apply tool remains in-app-only because its one-use safety handoff depends on authenticated in-app chat-turn provenance; the external preview instead parks a proposal an admin approves in the app. This inbound OAuth lets external clients access Cantinarr; it is separate from the outbound personal/shared OpenAI OAuth used by Codex chat. Every tool can be toggled on/off from Settings > AI Tools.
• Deep arr control -- SABnzbd, qBittorrent, NZBGet, Transmission, Deluge, and ruTorrent modules with live queue management (an aggregate All view with a master pause across every client when several are configured), plus drill-down Radarr/Sonarr control: series → season → episode with per-item progress, quality, and history; episode multi-select with batch search; long-press action menus; Edit Series and Edit Movie; links out to IMDb, TMDB, and Trakt (plus TheTVDB for series), and from a Chaptarr book to Goodreads, Open Library, and the Hardcover page Chaptarr declares; interactive release search everywhere. Admin AI/MCP tools can inspect quality profiles and import or update native/TRaSH custom formats across Radarr, Sonarr, Chaptarr, and Lidarr. After an explicit admin request, in-app AI previews and autonomously applies a narrow profile score, cutoff, or upgrade-policy change in the same authenticated chat turn. AI/MCP profile and custom-format writes are recorded under Settings > Configuration history for later review and live comparison. Each applied quality-profile update can be restored once, only while Cantinarr's instance, profile, and dependency guards still match; the linked restore is final, and custom-format entries are review-only.
• Import Doctor -- when a download is stuck, Cantinarr explains why in plain English (sample file, un-extracted archive, unconfirmed TheXEM mapping, "not an upgrade", unparseable/invalid file, remote-path-mapping or download-client problems, stalled torrent, permissions...) and offers one-click fixes with full transparency: manual/force import with the candidate files shown, remove + blocklist + re-search, hand-off to a tool like Unpackerr, or rescan. Cantinarr clears the stuck item and leaves the replacement to your service's own settings — with one exception: when the download was only an upgrade for something you already have and nothing asked for it (your service picked it up on its own), it is simply dropped. Your copy stays watchable, and a better version is still picked up whenever one shows up. The same diagnosis backs the app, the AI assistant, the remediation agent, and MCP.
• Flexible requests -- request a whole title in one tap, or pick exactly which seasons (or book formats) you want; partially-available shows surface per-season availability and a one-tap path to request the rest.
• Always in sync -- availability is computed live from the arrs (never from a stale snapshot), and server-managed Radarr/Sonarr/Chaptarr/Lidarr webhooks -- installed automatically the moment you add an instance -- push manual imports, deletes, and adds into the app the moment they happen without exposing callback credentials to a device. Books gain the most: an ebook can finish downloading between two polls, so instant updates are what make its "ready to read" alert reliable.
• Push notifications -- APNs (iOS) and FCM (Android) via a self-hosted push gateway with zero-config auto-enrollment: new-content alerts for movies, episodes, and books, approval/issue alerts for admins, per-user preference toggles, deep links into the right screen.
• Plex, Jellyfin, and Emby access -- connect your media server and choose which users get access. On Jellyfin or Emby each of them creates their own account from the app with a password only they know, or links one they already have by signing in with it once (administrator accounts included; Cantinarr never changes those); on Plex they sign in with their own Plex account, or share its email, and the invite goes out the moment you grant them (or on its own, with auto-approve). Already have users on the server? Import them from Users: each picked account becomes a Cantinarr user of the same name, granted and linked, with a connect link to hand out. Everyone sees the libraries you picked and the address to sign in at, an available title's page gets a Watch on Plex / Watch on Jellyfin / Watch on Emby button backed by a live lookup with their own access. On iOS and Android it opens the installed media app (the title where supported, otherwise the app home), with the exact web title as fallback when the app cannot open; web and desktop keep the web title link. When Plex cannot verify the title, Open Plex opens the app home on mobile or the configured sign-in address as fallback, and the app shows the live state: invite pending, accepted, or switched off. Take access away and a Jellyfin or Emby account is switched off rather than deleted, so watch history survives, and a Plex share is removed; grant again and it comes back (for someone still connected to your Plex account, without another invite).
• Monitoring -- watch what's playing right now: active streams with quality/transcode badges and the server they play from, watch history, and top movies/shows/users stats. Tautulli covers Plex; Tracearr covers Plex, Jellyfin, and Emby from one instance, and both feed the same module.
• Secrets encrypted at rest -- arr API keys, download-client passwords, webhook tokens, shared and personal AI credentials, and OpenAI/xAI OAuth authorizations are AES-256-GCM encrypted in the database.
• Household-friendly -- Connect links, passwordless by default, role-based access, kids accounts, per-user default instances. Admins manage services; users just browse and request.
• Guided setup -- a live checklist wizard derived from what's actually configured: every step opens the real settings screen, progress can't go stale, and newly shipped features appear on the list automatically.
• Single container -- The static Go API/web server plus a pinned Codex app-server helper, with one exposed port. Runs great on a Raspberry Pi or NAS.

Quick Start

git clone https://github.com/windoze95/cantinarr.git
cd cantinarr
docker compose up -d

services:
  cantinarr:
    image: ghcr.io/windoze95/cantinarr:latest
    ports:
      - "8585:8585"
    volumes:
      - ./config:/config
    # Optional: enables push notifications (see Configuration)
    # environment:
    #   - CANTINARR_PUSH_GATEWAY_URL=https://push.cantinarr.com
    restart: unless-stopped

Unraid

curl -o /boot/config/plugins/dockerMan/templates-user/my-cantinarr.xml \
  https://raw.githubusercontent.com/windoze95/cantinarr-unraid/main/templates/cantinarr.xml

Prebuilt binaries (no Docker)

tar -xzf cantinarr-linux-amd64.tar.gz
install -m 0755 cantinarr codex-app-server /usr/local/bin/
mkdir -p /config   # database + generated encryption key live here
cantinarr          # serves everything on 8585 (CANTINARR_PORT overrides)

From Source

# Server (requires Go 1.25+)
cd server
go run ./cmd/server

# App (requires Flutter stable, Dart SDK 3.4+)
cd app
flutter pub get
flutter run

Get the app

• iPhone and iPad -- join the public beta on

• Android -- ask for a tester slot. Play

• Any browser -- your server already serves the full app at

Repository Structure

cantinarr/
├── server/                 # Go backend -- see server/README.md
│   ├── cmd/server/         # Entry point
│   └── internal/           # ai, api, arr, auth, cache, chaptarr, codexapp,
│                           # config, credentials, db, deluge, discover, downloads, emby, grokoauth, httpx, instance, jellyfin,
│                           # mcp, mcpserver, mediaaccess, mediafiles, mediapath, mediaserver, nzbget, proxy, push, qbittorrent,
│                           # radarr, remediation, request, rutorrent, sabnzbd, secrets,
│                           # sonarr, tautulli, tmdb, tracearr, trakt,
│                           # transmission, watchhistory, web, webhooks,
│                           # websocket
│
├── app/                    # Flutter client (iOS, web) -- see app/README.md
│   ├── lib/
│   │   ├── core/           # Models, networking, realtime, theme, widgets
│   │   ├── features/       # auth, discover, request, dashboard, sonarr,
│   │   │                   # radarr, chaptarr, downloads, media_download, monitoring, issues,
│   │   │                   # ai_assistant, notifications, settings, ...
│   │   └── navigation/     # GoRouter with auth guard
│   └── test/
│
├── Dockerfile              # Multi-stage build (Flutter web + Go)
├── docker-compose.yml      # Full-stack deployment (push env pre-wired)
├── AGENTS.md               # Contributor/agent operating manual (CLAUDE.md imports it)
└── README.md               # This file

Configuration

How It Works

For Users

1. Admin sends you a connect link
2. Open the link on your device -- it creates your account and connects automatically
3. Browse movies, TV shows, books, and music powered by TMDB, Trakt, ListenBrainz, MusicBrainz, Chaptarr, and Lidarr
4. Tap "Request" on anything you want -- pick seasons for a show, tap a book's eBook or Audiobook row to request that format, or request an album
5. Watch download progress live and get push notifications
6. Something wrong with a file? Tap "Report a problem"; Cantinarr quietly watches for an in-flight Radarr/Sonarr recovery, then investigates only if the problem persists
7. Ask the AI assistant for recommendations or to make requests for you. Use the included server provider when granted, or choose your own provider under Settings > AI Access
8. Sharing a media server? Open Watch on Plex / Watch on Jellyfin / Watch on Emby in the menu: create your account or sign in with one you already have (Jellyfin, Emby), or sign in with Plex or share your Plex email and accept the invite (Plex), then sign in at the address shown; an available title's page in Cantinarr also has a Watch on button when the media server confirms the match, or Open Plex when an exact Plex link cannot be verified

For Admins

1. Deploy the container and complete the setup wizard
2. Add your shared API credentials and service instances from Settings; for included AI, either add an Anthropic/OpenAI/Gemini/xAI key or link a shared OpenAI (OAuth) or xAI Grok (OAuth) account; a Plex, Jellyfin, or Emby instance also chooses which users get access there
3. Invite your household from Settings > Users (set Settings > External Address first so links work away from home), grant included AI access where wanted, and pin per-user default instances if you run several
4. Optionally require approval for requests -- pending ones arrive as push notifications
5. Instant updates come on by themselves: adding a Radarr/Sonarr/Chaptarr/Lidarr instance installs the server's authenticated webhook automatically (books need it most -- an ebook can finish downloading between two polls). Each instance's edit screen shows the live state and a Configure instant updates button to repair it -- e.g. after changing CANTINARR_ARR_CALLBACK_URL
6. Manage everything from the app -- queues, stuck imports, issues, agent fixes. No config files.
7. Updating means pulling the newer image and recreating the container -- see docs/updating.md. Optionally set an Update Portal link (Settings > Admin) so an in-app update warning jumps straight to your container manager.

ID Bridge (TMDB-to-TVDB)

Request: "Add The Last of Us" (TMDB ID 100088)

1. Cache check     -> miss
2. TMDB external_ids API -> tvdb_id: 392256 (hit!)
3. Cache result (30 days)
4. Sonarr lookup by tvdb:392256 -> exact match
5. Add to Sonarr with the user's effective quality profile + root folder

Tech Stack

API Reference

Related Projects

• mam-chaptarr-protonvpn-skill -- an agent skill for building the layer below Cantinarr's books module: a VPN-isolated Gluetun/ProtonVPN stack running Chaptarr and qBittorrent in one network namespace, with forwarded-port sync, separated indexer and tracker-host sessions, and end-to-end verification. Useful if you're standing up book automation from scratch and want the container topology right the first time. Independent project; docs/books-setup.md shows where it fits.

Contributing

• Pull requests -- fork, branch, and open one. Run the checks first (go vet ./... and go test ./... from server/; flutter analyze --no-fatal-infos and flutter test from app/), and update any doc your change makes untrue. CI runs the same checks on every PR, and a first-time contributor's run needs one approval from the maintainer before it starts. For anything large, open an issue first so the shape can be agreed before you build it.
• Bugs and technical issues -- open one on the issue tracker.
• Feature requests -- post and vote at cantinarr.com/roadmap, no account needed.

Community

Support

Attribution

License