JavBoss: a self hosted media library with built in metadata scraping

One application for the whole local video library, not a separate scraper

JavBoss is built around a simple idea: the media library, the metadata and the player should be one program rather than three. The project describes itself as a local video manager that scans directories, generates cover screenshots, recognises the content, scrapes metadata, offers search and plays back through a built in mpv player. The README is blunt about the positioning, comparing itself to the usual combination of a dedicated scraper plus a general media library and saying this project is customised for its scenario rather than assembled from parts.

Two run modes sit behind the same interface. One is a plain video mode for an ordinary film or home video collection, the other is the scenario the tool is named after, where filenames are matched against a catalogue and the entries gain performer, studio and series information. The mode is a switch, so the same installation can hold both kinds of library.

The design constraint the project keeps repeating is that it never writes into your video folders. Scanning, screenshot generation and scraping all read, and the runtime data is kept in a separate directory. That is a sensible default for a tool that touches a large collection on a NAS, and it is the reason you can point it at a directory of files you care about without worrying about a bug rewriting them.

What happens during a scan: read files, cut a screenshot, look up the name

The scan is the engine behind everything. When you add a directory under the directory management settings, the program walks it, finds the video files, and for each one produces a cover screenshot and tries to identify it. The screenshot step is why the container image includes ffmpeg, and the file type detection in the Go dependencies uses a content based library rather than trusting the extension.

The metadata side is scraping. The project depends on an HTML parsing library and carries a proxy configuration setting, which fits a tool that queries several catalogue sites and has to cope with regional network conditions. The result of a scan is stored in a SQLite database through an ORM, with schema migrations managed by a dedicated migration tool, so the catalogue of what you own is local and searchable. The README states that everything already displayed comes out of the data directory and stays available offline, and that being unable to reach the internet only stops new scraping and updates.

The state attached to a video is bound to a fingerprint of the file itself, so tags and play counts survive a rescan after a rename or a move, as long as it is the same file. That is the detail that makes the tool usable, because a media library changes shape constantly.

Installing with the one line script, or as a container

There are three documented ways in, and the script route is the shortest. On Linux and macOS the project publishes a one line installer that downloads the matching release build and starts the program.

curl -fsSL https://raw.githubusercontent.com/Solr159/JavBoss/main/scripts/install.sh | bash

Afterwards the command is javboss in a terminal. The default install location is stated as ~/.local/share/javboss on Linux and ~/Applications/JavBoss on macOS, with the Windows equivalent under the local application data directory, and the Windows build also adds a desktop shortcut and a system tray entry, while the macOS build sits in the menu bar.

The manual route is a zip per platform, with separate archives for Linux, Windows, macOS on Intel and macOS on Apple silicon. The container route suits a NAS, and the compose file is small.

services:
  javboss:
    image: ghcr.io/solr159/javboss:latest
    container_name: javboss
    network_mode: host
    command: ["./javboss", "-port", "8655"]
    environment:
      JAVBOSS_PROXY_HOST_GATEWAY: "0"
    volumes:
      - ./data:/app/data
      - /:/host
    restart: unless-stopped

Start it with docker compose up -d, then open the browser at http://localhost:8655. The default login password is admin, and the documentation points you to the security section of the settings to change it.

The container mounts the host filesystem because NAS paths are not container paths

Two things in that compose file deserve attention. The volumes section mounts the data directory for runtime state and mounts the host root at /host, and the documentation explains why: when you add a directory you type the host path, for example a mounted disk such as /mnt/disk1/videos, and the program maps it to a path the container can reach. Without the host mount, the container would not see the library it is meant to index.

The second thing is network_mode: host, combined with the -port 8655 argument. Host networking means the port is not published through a mapping, which is convenient for a NAS where other services already have their ports, and the documentation notes that the container deployment reaches the local network by default while other installation types have to enable that in the network and proxy settings. The trade is that the service is exposed on every interface of the machine, which is why changing the default password matters.

The compose file also notes that it changed in the v2.1.0 release and that existing users should update it, which is a hint that the configuration is still moving. One environment variable is visible, JAVBOSS_PROXY_HOST_GATEWAY, set to 0, and the dependency list includes a proxy library for Windows, so proxy handling is a supported path rather than an accident.

Scraping is rate limited, so a single pass never finishes the job

This is the most useful thing the documentation tells you, and it is stated bluntly. A scan attempts to scrape each video once, and roughly 1 percent of attempts fail, whether because of network jitter or because the target site applied risk control. The project says to run the scan again. There is no queue, no retry policy and no guarantee of completeness after one pass.

The cadence is configurable. By default the program keeps scanning on its own with one minute between passes, and the interval or automatic scanning itself can be changed under the scan settings in the directory management panel, while a manual scan button triggers a pass immediately. The documentation recommends increasing the interval or turning automatic scanning off for long running NAS installations, and gives the reason plainly, which is the life of the hard drives.

A second piece of advice concerns the enrichment order. Performer, studio and series information fills in over time, and the documentation gives a rough speed, with performers arriving fastest, studios next and series slowest. If you are judging the tool on the first five minutes after adding a library, you will see it at its least complete, and the sensible test is whether a second and third pass improve the result.

The browser extension reaches outside the app, including magnet downloads

An optional Chrome extension ships with the program packages, and it is the part that pushes the tool beyond a local catalogue. It has four functions. The first backfills a manual scrape, so you open the detail page of an entry on an external site and a button in the corner of the page extracts the information and sends it back to JavBoss to check and save. The second is a shortcut that jumps from a card in the app to the corresponding detail page on JavDB, with an option to fall back to a search page instead. The third marks entries as already owned on external listing and detail pages.

The fourth is a magnet link download. Enable it in the extension, click a magnet link on any page, confirm, and the job is submitted to the JavBoss download queue, where it becomes a CloudDrive2 offline task that pulls the file to a local directory. That path needs CloudDrive2 and a local download directory configured in the download settings first, and the owned status and magnet features need a connection to JavBoss, which uses an API token created in the global settings under the security section and pasted into the extension's connection settings with a test connection button.

The extension is optional and is downloaded separately from the release page, and it should be treated as the highest risk surface in the project because it operates on arbitrary websites and triggers downloads.

Client mode turns a desktop install into a proxy for a remote library

The Client mode solves a specific problem. If JavBoss runs in a container on a NAS and you open it from a laptop in the same building, the built in player is a web player, because the container has no mpv and no display. Client mode fixes that by running a second JavBoss on the local machine and pointing it at the remote one, so the local instance acts as a reverse proxy in front of the remote server, browses the remote library and plays the video with the local mpv, including local player settings and automatic screenshot synchronisation.

The remote address goes into config.toml in the program directory.

server_url = "http://192.168.1.100:8655"

The same value can be passed as a command line argument, --server-url http://192.168.1.100:8655, which is the quicker option for a one off. The same file holds the port setting, so changing the listening port is an edit to the port value in config.toml rather than a command line flag, and the compose example above sets it with the -port argument instead.

The runtime data lives in a data directory next to the program, which is what makes migration simple. Moving to a new machine means downloading the build for the new system and copying the data directory across, then editing the directory entries if the video paths changed. For Docker users the upgrade is a pull and a restart.

A Go service with a Node frontend, and documentation written by a self described lazy author

The build setup shows a two language project. The Dockerfile is multi stage, with a Node 24 stage on bookworm slim that installs the web frontend and builds it, a Go 1.25 stage that compiles the server binary from ./cmd/server with version information injected through linker flags, and an Alpine stage that adds ffmpeg. The Go side depends on gin for the HTTP server, an ORM with a SQLite driver, a migration tool, a query builder for scraping, a terminal UI library with form widgets, a system tray library, a process information library, a rotating log writer, gRPC and protobuf, a proxy library for Windows and a Chinese conversion helper.

The release history is active. Versions v2.1.2, v2.1.1 and v2.1.0 were published in October 2026, and the last push was on 2026-10-18. The licence is GPL-3.0, which matters if you plan to modify the code and ship it, and the project asks in its risk notice that users follow the law of their region and not use it commercially, describing itself as a practice project written while learning Go.

That same notice explains the documentation. The README quotes the author saying they are lazy and dislike writing documentation, and lists batch deletion, manual scraping, directory organisation, exporting nfo files and covers as features you are expected to discover yourself. Development documentation exists in a separate file, and the tree also holds an agent instruction file, a source quality document and a local compose file, so the project is more organised than the README implies. Just do not expect a written guide for every feature.

Editorial conclusion

Adopt JavBoss if you keep a large local video library on a NAS and want one application to index it, generate posters, enrich the entries and serve the interface over the network, and accept that metadata comes from scraping third party sites that can rate limit you. Do not adopt it if you need reliable, complete metadata on the first pass, since the project states that roughly 1 percent of videos fail to scrape per run and need a second scan. Before you deploy it, change the default admin password under the security settings, set the scan interval in the directory management panel to something other than one minute if the library sits on spinning disks, and pin the container image to a specific tag rather than latest.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. Releases
5. Solr159/JavBoss on GitHub