Table of Contents
Docker
docker compose up -d --build
The compose file builds the local checkout and runs Kaizoku on port 8421 by default. KAIZOKU_PORT changes the published host port; the app continues listening on port 8421 inside the container. It mounts:
./downloadsto/downloads${JELLYFIN_TV_DIR:-./jellyfin/tv}to/jellyfin/tv${JELLYFIN_MOVIE_DIR:-./jellyfin/movies}to/jellyfin/movies./.kaizokuto/app/.kaizoku${KAIZOKU_BACKUP_HOST_DIR:-./backup}to/backupfor watchlist ZIP backups
Use /jellyfin/tv for the Jellyfin TV directory and /jellyfin/movies for the Jellyfin movie directory inside the Config page. Override JELLYFIN_TV_DIR and JELLYFIN_MOVIE_DIR to point those container paths at your real host Jellyfin library folders.
If filesystem monitoring is unavailable (for example with some Samba mounts), enable Refresh after handoff and enter the Jellyfin server URL, an API key created in Jellyfin's API Keys dashboard, and the exact library name or item ID. After a successful handoff batch copies all queued files, Kaizoku resolves that virtual library and calls Jellyfin's item-refresh API once. It does not start the server-wide /Library/Refresh scan.
Kaizoku sends the API key with Jellyfin's current Authorization: MediaBrowser scheme, which is required by Jellyfin 12 and remains compatible with earlier supported servers.
The Docker image installs Python, Node.js, curl, curl-impersonate browser wrappers, ffmpeg, openssl, and util-linux for optional UID/GID switching. A separate build stage runs npm ci --omit=dev and copies only the provider bridge dependencies into the runtime image. Downloads go through Kaizoku's provider bridge and provider_downloader.py.
Useful Compose overrides:
KAIZOKU_PORT=8080 docker compose up -d --build
KAIZOKU_ALLOW_REMOTE=1 KAIZOKU_AUTH_USERNAME=admin KAIZOKU_AUTH_PASSWORD='change-me' docker compose up -d
USER_UID=$(id -u) USER_GID=$(id -g) docker compose up -d
When USER_UID and USER_GID are set, the entrypoint attempts to adjust ownership for /downloads, /jellyfin/tv, /jellyfin/movies, /backup, and Kaizoku state paths. Ownership changes are best-effort so policy-managed or read-only Jellyfin mounts can still be browsed and used when their existing permissions allow it.
Keep ./.kaizoku mounted for production instances. That directory contains the SQLite database, configuration, queue history, watchlist data, thumbnail cache, remote sessions, and temporary staging files. Removing the mount starts Kaizoku with a fresh empty state.