Plembfin is a self-hosted Node.js application.

It keeps the watch archive in local SQLite and makes provider requests from the machine where Plembfin runs.

Start with the instance itself. A media server is optional during setup, so you can claim Plembfin and configure metadata, private lists, or backups before connecting Plex, Emby, or Jellyfin.

Trakt, metadata providers, webhooks, and remote backups can be added after the core connection is healthy.

Before you install

Plembfin Settings landing page used to plan connections, metadata, backups, and setup
The instance can be claimed and configured before any media server is connected.

Have these ready:

  • A host that can reach each media server by its configured URL.
  • Persistent storage for Plembfin’s /data directory.
  • A strong administrator password.
  • A Plex token, Emby credentials/API key, or Jellyfin credentials/API key if you are connecting a media server during setup.

The browser is only the client.

A connection can look reachable from your laptop while the Plembfin host cannot reach it.

Network testing must ultimately be done from the host that runs the application.

Install with Docker Compose

Create a folder for Plembfin and put a private .env file beside the Compose file:

ADMIN_PASSWORD=choose-a-strong-private-password

Create docker-compose.yml:

services:
  plembfin:
    image: ghcr.io/lasikiewicz/plembfin:latest
    container_name: plembfin
    ports:
      - "5055:5055"
    volumes:
      - ./data:/data
    environment:
      ADMIN_USERNAME: admin
      ADMIN_PASSWORD: "${ADMIN_PASSWORD:?Set ADMIN_PASSWORD in .env before starting}"
    restart: unless-stopped

Start the container and open http://localhost:5055:

docker compose up -d

The /data volume is essential.

It keeps the database, settings, credentials, artwork cache, logs, and backups across container recreation or upgrades.

Back up this directory and use Plembfin’s own backup tools for a portable archive.

Install with Node.js

For a bare-metal install, use Node.js 22.19.0 or newer.

From the repository root:

npm install
npm start

Open http://localhost:5055.

For connected-service testing, start Plembfin from a host or network-enabled terminal. A restricted sandbox can reach the local page while still blocking requests to Plex, Emby, or Jellyfin.

Use npm run dev during development when you want server files to reload as they change.

Claim the instance

On a fresh install with no administrator password, Plembfin shows:

Claim this Plembfin instance

Create the administrator username and password there.

Claiming is a one-time action and should only be done by the person who controls the server.

After claiming, Plembfin opens the resumable setup guide.

You can reopen it from Settings → Tools → Guided Setup.

A setup step can be skipped and completed later; the guide does not replace the individual settings pages.

Complete the guided setup

Plembfin Guided Setup control showing the resumable onboarding flow
Guided Setup organizes optional services into resumable steps rather than requiring one long first run.

Work through the stages in this order when possible:

  1. Overview — confirm the instance is running and see which optional services are available.
  2. Trakt — optionally connect Trakt or import an existing history archive.
  3. Metadata — add a TMDB key first; add TheTVDB, Fanart.tv, OMDb, or YouTube when you need their additional data.
  4. Media servers — optionally connect and test Plex, Emby, Jellyfin, or more than one server.
  5. Webhooks — configure Emby or Jellyfin event delivery. Plex’s built-in listener does not need a manual webhook.
  6. Backup — schedule local backups and optionally configure a Backblaze B2 mirror.
  7. Import & sync — watch the import and delivery status rather than starting another full sync immediately.
  8. Options — choose watched-flag handling in Sync Tuning. Require review sends provider Mark Played events without a reliable completion time to Manual Watch review; Fast Local-Network Sync is available only for trusted local networks.
  9. Review — confirm each step and open the dashboard.

The Media servers stage is part of Guided Setup. If you skip it, return later through Settings → Media servers rather than repeating an onboarding step here.

Confirm the first sync

The dashboard is the quickest health check after a server is connected.

It separates Now Playing, a mixed Up Next queue containing resume items and released TV episodes, and completed TV and movie history rows. Before a media server is connected, use the setup steps and Settings to confirm the instance itself is healthy.

The sidebar sync indicator is only a summary.

For the reason behind a result, open Sync Activity and inspect the source, destination, outcome, and message.

Plembfin dashboard showing Now Playing, Up Next, watch history, and movie activity
After connecting a server, use the dashboard to confirm that activity is being recorded and the library is populated.

If history is missing, check the media-server connection.

Then check troubleshooting.

If an event is recorded but not delivered, use the Sync Activity guide before running a whole-library repair.

What to do next