Table of Contents
Setup and Configuration
- Python 3.12 or newer.
- Node.js and npm for the provider bridge.
ffmpegavailable inPATH.opensslavailable inPATHfor AES-128 encrypted HLS segments.pytestis optional; the current regression tests areunittest-compatible and can run with the Python standard library.- Docker builds install the locked Node dependencies with
npm ci; rebuild the image after dependency updates.
Install Node dependencies once:
npm install
Run locally:
./kaizoku
Then open:
http://127.0.0.1:8421/
Local runs store scheduled watchlist ZIPs in ./backup; Docker uses the /backup mount. Set KAIZOKU_BACKUP_DIR to use another backup directory outside Docker.
For Uptime Kuma or another HTTP availability monitor, use http://IP:PORT/status. GET returns HTTP 200 with OK; HEAD also returns HTTP 200. The endpoint needs no authentication and reports whether Kaizoku's HTTP server is responding. It does not check provider or download health. For a monitor on another machine, bind Kaizoku to a reachable address and set KAIZOKU_ALLOW_REMOTE=1; the normal app and API routes still require configured credentials for remote clients.
For a dashboard, request GET /api/watchlist/homepage?include_downloads=1. The usual watchlist, planned, finished, dropped, and total counts remain, and downloads adds total, running, pending, failed, and a jobs array. downloads.total counts the jobs in these three states. Each job includes id, name, title, status, episodes, mode, provider, and available progress fields such as percent, episode, and message. name is the task name, with title retained for existing dashboard clients. The array lists running, pending, and failed downloads in that order, including live progress for the current job; completed and canceled jobs and Jellyfin handoffs are excluded. Without the query option, the response has the original counts only. This route always requires HTTP Basic auth, even for local requests. It uses the KAIZOKU_AUTH_USERNAME and KAIZOKU_AUTH_PASSWORD supplied to Docker Compose; set both before starting the container. A missing or invalid Basic header receives HTTP 401 with a WWW-Authenticate challenge.
curl -u 'admin:your-password' 'http://IP:PORT/api/watchlist/homepage?include_downloads=1'
Run the local regression tests:
python3 -m unittest -q
Useful environment variables:
KAIZOKU_HOST=0.0.0.0KAIZOKU_PORT=8421KAIZOKU_ALLOW_REMOTE=1to allow non-loopback clients.KAIZOKU_AUTH_USERNAME=adminandKAIZOKU_AUTH_PASSWORD=choose-a-long-random-passwordfor remote access.KAIZOKU_JOB_STDOUT=trueto mirror job logs to container or terminal output.KAIZOKU_STATE_ROOT=/path/to/stateto move SQLite state, config, thumbnails, sessions, and staging.KAIZOKU_DOWNLOAD_DIR=/downloadsfor the default library output path.KAIZOKU_REMOTE_PATH_ROOTS=/downloads,/jellyfin/tv,/jellyfin/moviesto limit remote filesystem browsing; comma-separated and platform path separators are accepted.KAIZOKU_MODE=sub,KAIZOKU_QUALITY=best, andKAIZOKU_DEBUG=1for runtime defaults and diagnostics.KAIZOKU_SEGMENT_RETRIES=8,KAIZOKU_SEGMENT_RETRY_DELAY=1.25,KAIZOKU_SEGMENT_RETRY_MAX_DELAY=15, andKAIZOKU_SEGMENT_DOWNLOAD_DELAY=0to tune retry/backoff and optional pacing behavior for native HLS segment downloads. Retries cover temporary HTTP responses, DNS failures, connection errors, and socket timeouts.KAIZOKU_MEDIA_HTTP_CLIENT=autoto let protected HLS segment fetches fall back from Python HTTP tocurlor curl-impersonate afterHTTP 403; usecurlorurllibto force one client, andKAIZOKU_CURL_BIN=/path/to/curl_chrome142to prefer a specific curl-compatible binary. Playlist, segment, and encryption-key requests preserve provider CDN session cookies for the duration of the download process.