Introduction

Sovereign is a self-hosted media server for streaming locally stored movies and TV series to multiple clients over a network - similar in purpose to Plex, Jellyfin, or Emby.

Not released yet

Sovereign hasn’t had its first release, so the server image and the Roku and Android apps aren’t available to download yet. These pages describe Sovereign as it will ship; Availability says what’s coming.

Reading with an AI agent?

All of these docs are also available as plain-text files for LLMs, following the llms.txt convention:

• /llms.txt - a structured index of every documentation page
• /llms-full.txt - the complete documentation concatenated into a single file

---

What is Sovereign?

Sovereign runs on your own hardware, and your files and viewing history stay there. Playback doesn’t depend on any cloud service, and what you watch isn’t sent to us or to anyone else outside your server.

Once it’s running, Sovereign finds your media, fetches its metadata, and streams it to a browser, a TV or a phone, transcoding only when the device can’t play the file as it is.

---

Key Features

• HLS streaming - FFmpeg repackages each file, or transcodes it when the client needs that, and delivers it as HTTP Live Streaming (HLS) to Sovereign’s web, Roku and Android apps
• Trickplay thumbnails - Scrub previews are generated automatically the first time a file is played
• Protected media links - Links to videos, images and subtitles are handed out only to signed-in users, each works for one file, and each expires within about a day
• Web, Roku and Android clients - A web app served by the server itself, a Roku channel, and Android apps for phones, Android TV and Google TV, and Fire TV. Televisions sign in with a short code you approve from a phone or computer
• Hardware transcoding - NVIDIA, Intel Quick Sync and VAAPI (Intel and AMD) GPUs are detected at startup and used when they work, with software encoding as the fallback
• OAuth 2.0 / OpenID Connect - Authentication is handled by OpenIddict with refresh tokens to keep sessions alive, a device-code flow so televisions sign in without typing a password, and optional sign-in with Google or Microsoft
• GraphQL API - Library data, settings and live updates go through a single HotChocolate GraphQL endpoint, while video and artwork come from short-lived links
• Library management - Integrates with Radarr (movies) and Sonarr for automated library monitoring and import, or imports a directory of media files directly
• Rich metadata - Movie metadata is sourced from TMDb; TV series metadata comes from TheTVDB, or from TMDb for series imported from a directory
• Licensing that never locks you out - An unlicensed server plays everything a licensed one does and shows a notice instead. See Licensing
• Zero-config database - Embedded SQLite, no separate database server to run or tune
• Docker-first deployment - Distributed as a Docker image; a single compose.yaml brings up the full stack

---

How It Works

Sovereign sits between the tools that manage your library and the apps you watch on. Keeping the library up to date, then playing a title, goes like this:

sequenceDiagram
    participant Arr as Radarr / Sonarr
    participant Meta as TMDb / TheTVDB
    participant Sov as Sovereign
    participant App as Client device
    Sov->>Arr: Anything new?
    Arr-->>Sov: New files
    Note over Sov: Also scans any media<br/>folders you've pointed<br/>it at
    Sov->>Meta: Look up each title
    Meta-->>Sov: Details and artwork
    Note over Sov: Stores it all in its<br/>own database
    App->>Sov: Play this title
    Note over Sov: Repackages the file, or<br/>transcodes it if the app<br/>can't play it as it is
    Sov-->>App: The stream
    App->>Sov: Progress as you watch

The Sovereign server polls Radarr and Sonarr for library changes, scans any media directories you’ve pointed it at, fetches metadata from TMDb and TheTVDB, and stores everything in a local database. When a user plays a title, the server spins up an FFmpeg pipeline that repackages the file, or transcodes it when the client can’t play it as it is, and serves the stream as HLS. Every client talks to the server over GraphQL (HTTP for queries and mutations, WebSocket for live subscriptions) and fetches video and artwork from signed, short-lived URLs. Because they all share one server, your library, watch progress and settings follow you between them. See Interface for what each one covers.

---

Tech Stack

Layer	Technology
Backend	ASP.NET Core (.NET 10)
API	HotChocolate GraphQL
Frontend	React 19, TanStack Router
TV and mobile	Roku SceneGraph, Android
Authentication	OpenIddict (OAuth 2.0 / OIDC)
Transcoding	FFmpeg (via FFMpegCore)
Database	EF Core - SQLite
Deployment	Docker / Docker Compose

---

Getting Started

Sovereign runs as a single container, which serves the web app itself, so there’s no separate frontend container to run. Getting Started sets it up with Docker Compose, and the Docker and Kubernetes pages cover the other ways to run it.

See the Configuration section for the full list of settings and their defaults. Most settings have sensible defaults, so all you have to set is a media volume mount, your Radarr/Sonarr connection details (or a media directory), and the public HTTPS address your users reach the server at.