Jellyswarrm: a Rust reverse proxy that merges several Jellyfin servers

One endpoint in front of several Jellyfin instances

Jellyswarrm is a reverse proxy that combines multiple Jellyfin servers into one place. The problem it solves is concrete: a person with a library at home and another shared with friends, or several servers across locations, ends up switching between them inside a client that was never designed for that. The README argues that some Jellyfin apps do support multiple servers but that switching between them can be inconvenient, and that Jellyswarrm also merges Next Up and Recently Added across all servers so you can see what is new in your own libraries or what a friend has added. The implementation is Rust, and the workspace splits into three crates: jellyswarrm-proxy, jellyswarrm-macros and jellyfin-api. The proxy crate holds the axum server, sqlx with SQLite for its own state, tokio for the async runtime, and reqwest with rustls for talking to the upstream Jellyfin servers. That structure is what makes it a proxy rather than a fork: it does not reimplement Jellyfin, it sits in front of several instances and federates them.

It presents itself as an ordinary Jellyfin server

The design decision that makes Jellyswarrm usable is listed among the working features as API compatibility: it appears as a normal Jellyfin server, so existing apps and tools still work. A client that knows how to talk to Jellyfin needs no special support to talk to Jellyswarrm. The README is careful about the limits of that claim, saying most clients should work out of the box while noting that not every Jellyfin client has been tested and a few may have issues. That is the right way to state it, because the proxy has to reproduce an API surface that upstream keeps changing. Users are also mapped across servers, linking accounts so the same person has one identity on each instance, and there is server federation, which syncs users across connected servers automatically. A user page provides a personal dashboard for managing credentials and libraries. The credential handling is where the security design lives, and the workspace dependencies show the shape of it: aes-gcm for encryption, hkdf for key derivation, argon2 for password hashing, sha2 and sha1 for digests, and axum-login for the session layer.

Direct playback keeps transcoding next to the media

Direct Playback is listed as working, meaning content is played straight from the original server without extra overhead. The README's own FAQ explains why this matters more than it sounds: Jellyswarrm is built to connect your servers with your friends' servers across different networks, and setting up SMB in those cases can be complicated and often slower. With Jellyswarrm, content is streamed directly from the original server, so the heavy lifting such as transcoding happens where the media actually lives. That is the argument against mounting a remote library over SMB, and it is a good one for wide area links, where pulling a remote file over a network filesystem and then transcoding it locally is a much worse path than letting the origin server transcode. The same design also explains what Jellyswarrm is not trying to be. It is not a media manager, and it does not store anything itself; the data directory it mounts holds its own configuration and state, not your media.

Deploying the prebuilt image with two environment variables

The documented deployment is Docker, using the prebuilt images published for the project. The repository's own compose file builds from the Dockerfile in the root and maps port 3000, mounts a data directory and passes the credentials as environment variables:

services:
  jellyswarrm-proxy:
    build:
      context: .
      dockerfile: Dockerfile
    image: jellyswarrm-proxy:latest
    container_name: jellyswarrm-proxy
    ports:
      - "3000:3000"
    volumes:
      - ./data:/app/data
    environment:
      - JELLYSWARRM_USERNAME=admin
      - JELLYSWARRM_PASSWORD=jellyswarrm # Change this in production!
      - RUST_LOG=jellyswarrm_proxy=debug 

The README's own example instead pulls ghcr.io/llukas22/jellyswarrm:latest and uses the same two variables, JELLYSWARRM_USERNAME and JELLYSWARRM_PASSWORD, and the same port and data mount. Once it is running there are two entry points: the management web UI at the /ui path, where you log in with the configured credentials and add your Jellyfin servers and configure user mappings, and the bundled Jellyfin web client on the root path. Advanced configuration is documented in docs/ui.md and docs/config.md, and the /health and /ready endpoints are covered by docs/health-monitoring.md, which is the file to read before putting this behind a reverse proxy of your own.

The in-progress list is the honest part of the README

The README opens its feature section with a warning that Jellyswarrm is still in early development, that it works but some features are incomplete or missing, and that issues should go to the GitHub issue tracker. Under that, QuickConnect, which signs in on one device by approving a code from another authenticated device, is in progress. Websocket support is in progress and is needed for real-time features such as SyncPlay, and the README says it is not fully reliable yet. Audio streaming is in progress because progressive and HLS audio go through the video streaming path. Automatic bitrate adjustment based on network conditions is not supported yet, and media management, such as adding or deleting media libraries through Jellyswarrm, is not implemented. That list is more useful to an adopter than a feature matrix, because it tells you precisely which behaviours will disappoint. A SyncPlay user or someone who adds media from a phone will hit those limits immediately. Anyone whose use is browsing a unified library and playing from the origin server will not.

Building from source needs submodules, Node and the Rust toolchain

The development path is documented in enough detail to be reproducible. The repository uses submodules, and the README asks you to clone with them:

git clone --recurse-submodules https://github.com/LLukas22/Jellyswarrm.git

If the repository is already cloned, the same effect comes from:

git submodule init
git submodule update

The quick way to get a running instance is the provided compose file:

docker compose up -d

For a native build you need Rust and Node.js, and the UI dependencies are installed first:

cd ui
npm install
cd ..

Then the whole project builds with:

cargo build --release

A build.rs script in crates/jellyswarrm-proxy compiles the web UI and embeds it into the binary, so the result is a self-contained application, which is why the Node step is not optional. The repository also carries a justfile with the development stack commands, including a doctor target that checks that Docker and Docker Compose v2 are usable, and a setup target that fetches Git LFS media fixtures and starts the local Jellyfin, Caddy and Seerr services. Debug builds automatically register six local Jellyfin instances from data/jellyswarrm.dev.toml, two each for movies, TV shows and music.

Editorial conclusion

Jellyswarrm fits a household or small group that runs Jellyfin in more than one place, such as a home server plus a remote one, and that wants a single library view with transcoding left where the media lives. It does not fit a single-server setup, since the added proxy is pure overhead there, and it does not fit anyone who needs media management or SyncPlay to be dependable today. Verify first that the Jellyfin clients you actually use work through the proxy, because the README says most clients should work but not every one has been tested, and check the in-progress list before you depend on QuickConnect, websockets or audio streaming. The licence field on the repository says GPL-2.0, release v0.3.1 was published on 2026-10-05, and the last push was on 2026-10-17.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-2.0
3. LLukas22/Jellyswarrm on GitHub
4. README
5. Releases