Federation Companion

What Companion does on this computer

Runs in the background as your user and opens a local dashboard. You choose libraries and friends before sharing. Closing this browser leaves Companion running; use Exit Companion to stop it.

Permissions, downloads and saved data

Plex sign-in: contacts plex.tv and your selected Plex server; saves access tokens and sharing choices privately beside the app. Tokens are sensitive and are not encrypted by Companion.
Media folder (optional): Set up media folder enables rclone, downloaded from rclone.org if missing, and a read-only mount. On Windows it can download the pinned WinFsp driver from GitHub and ask for administrator permission. Linux needs FUSE; system permissions are yours to configure.
Disk and network: playback uses your connection and a local media-cache folder with a 2 GB cleanup target. Open files can exceed that target. Idle catalog sync runs every 30 minutes.
Remote access (optional): Private sharing exposes Companion's relay to approved Tailscale computers; Funnel exposes it publicly. Owner actions require the owner key; friends receive separate revocable access. Choose sharing only when you want it.
Start at sign-in (optional): writes a startup entry for your user only. You can switch it off below.
Updates: checks GitHub when you open the dashboard; installs an update only when you request it. Diagnostics stay in a rotating local log.

Windows builds are unsigned. SmartScreen may report an unrecognized app. A Defender malware detection needs investigation; do not disable protection or add blanket exclusions. See the permissions and verification guide.

✓ Owner access

Companion's public listener is locked so strangers cannot change your sharing choices. Paste the owner key (Windows: right-click the tray icon → Copy owner key; Linux: printed at startup), or open the dashboard URL with #access=… attached.

1 Tailscale

Checking…

2 Sharing connection

Private sharing connects your server computers without a public tunnel or port forwarding. Both computers need Tailscale access to the shared machine. Companion discovers its HTTPS address and relays only approved libraries. Public sharing remains available through Funnel or your own HTTPS address.

3 Plex Connection

Not connected yet.

Or connect a local Plex server with its address and token - no plex.tv account required, and your Jellyfin friend still does not need Tailscale.

4 Libraries to share

Original-file sharing (preview)

Companion can serve your approved original video files without using Plex's video-streaming service. It finds Plex's media folders automatically. Run Companion where those files are readable; the receiving Jellyfin server handles any required transcoding. Plex still supplies catalog metadata.

Different media-folder paths

If Plex runs in a container or uses different folder names, map its media folder to the same original files as seen by Companion. No files are moved. Only selected libraries are shared.

Plex media folder Same folder as seen by Companion

5 Connect a Jellyfin friend

Type their Jellyfin address. Companion sends the share request — they Accept under Federation → Companion. Your sharing address must reach this app. If it is down, Companion will not put your Plex token in the request; repair the connection or explicitly choose Plex Remote Access. Private sharing requires Tailscale access between the server computers; public sharing does not.

Optional: generate a code only if they cannot Accept from their dashboard and need to paste one.

Pool invites

Jellyfin friends can invite this Plex Companion into a Federation pool. Companion reports plugin version … so those invites are not rejected as an unknown plugin.

No pool invites yet.

Connected friends

No one connected yet.

1 Import from a Jellyfin friend

Paste a connect code from their Jellyfin Federation Companion tab. Choose which of their shared libraries to import. Plex needs the media mount below to analyze video/audio and play these titles; a catalog or a .strm link alone is not playable media.

The long-lived Jellyfin credential stays inside Companion. Plex receives only a stable link cryptographically bound to one exact movie or episode.

Set up the media folder once to enable the read-only helper. After that, Companion restores it when you launch the app. Keep Companion running while Plex scans or plays, then choose Add to Plex below.

Advanced: manual mount, separate machines, or Docker

Only needed when Companion and Plex are not on the same computer. For Docker, share the mounted folder with both containers.

Install rclone and its mount requirements (WinFsp on Windows, FUSE on Linux/macOS).
Save this on the Plex machine. It grants read access to imported media; keep it private.
In that folder, run the command for your system. Use an empty folder on Linux/macOS, or an unused drive letter on Windows. rclone mount companion: /path/to/empty-folder --config companion-rclone.conf --read-only --vfs-cache-mode full --vfs-cache-max-size 2G --dir-cache-time 30s rclone mount companion: X: --config companion-rclone.conf --read-only --vfs-cache-mode full --vfs-cache-max-size 2G --dir-cache-time 30s
Mounted folder as Companion sees it Same folder as Plex sees it
Choose Add to Plex on your friend below. Plex will scan the video files and detect their audio/video tracks. Existing libraries made from .strm files are left in place; remove those old library entries in Plex after verifying the new Streaming library.

Companion runs on a different machine

Companion address reachable from the mount machine

Use your LAN address here. Download the mount configuration again after changing it.

Legacy link export path mapping

Not importing from anyone yet.

⚙ Companion app

Companion keeps running in the background so Plex can reach the media folder and friends can connect at any time. On Windows it lives in the notification area (tray): right-click the icon to open this page, start or stop the media folder, copy the owner key, or exit.