12 KiB
Kaizoku
A local web app to search, track, and download anime from Anikoto and AnimePahe, with a retained legacy AniNeko adapter.
- Queue subbed or dubbed episodes and automatically download new releases.
- Organize shows in watchlists and save files in Jellyfin-friendly folders.
- Download available English subtitles and translate them to Czech with Ollama or OpenAI.
- Back up watchlists and receive Discord notifications.
The AI Subtitles page uses the same sidebar navigation and responsive layout as the other pages. Sign out is centered at the bottom of the left sidebar on every page.
Floating dialogs stay open when you click outside them or press Escape. Use their Save, Cancel, Close, or other action buttons to finish or dismiss them.
The Config sidebar's Provider updates panel wraps long messages and provider badges within its boundaries.
Search shows matches as soon as the provider responds. Episode counts, sub/dub availability, and alternative titles load afterward, two results at a time, without replacing cards or closing the selection dialog. Pending or failed audio checks remain visible and selectable; the Sub/Dub filter hides a title only once its availability is verified. Successful details are cached in memory for five minutes, while failed checks wait one minute before retrying on a later search. Starting a new search cancels further browser detail requests and ignores old responses. Provider response times still affect initial results. API clients retain the full search response by default; GET /api/search?fast=1 opts into deferred details from POST /api/search/details with id, title, and provider.
Search posters use one shared metadata request from the browser for up to 100 result titles. Kaizoku matches them against the search query's AnimeSchedule results (up to three pages of 18 entries), caches that metadata for five minutes, and serves matched images through its own authenticated image cache. External provider image URLs are skipped because the page's image policy blocks them. Image files still load individually, with at most four downloads at once and no per-title metadata lookup. Concurrent requests share lookups and downloads; source failures back off for at least a minute. Existing cached images remain available, while unmatched or temporarily unavailable posters show title initials. Broad searches can leave posters unmatched beyond the metadata page limit; watchlist thumbnail lookup remains independent.
Jellyfin handoff checks each downloaded TV season in Finished separately, verifies its season-specific completion metadata, and moves only that season and its sidecars once its expected video files are present. Other seasons remain in Downloads. Use Config → Handoff → Run now after updating to repair missing or incorrect season metadata and retry previously skipped seasons. If metadata cannot be verified, the queue reports the skip and retains the files for a later retry.
Quick start
With Docker installed, run from this checkout:
docker compose up -d --build
Prebuilt image: gitea.coreplay.eu/dymas/kaizoku:latest (also tagged by release version). The Docker image uses a separate build stage for npm dependencies to keep the runtime image smaller.
Open http://127.0.0.1:8421/. The backend binds to host loopback by default. For access through NPM, use the private-network overlay in SECURITY_DEPLOYMENT.md. For direct access from another device, explicitly set KAIZOKU_BIND_ADDRESS to a private interface address, restrict it with the host firewall, and set KAIZOKU_ALLOW_REMOTE=1, KAIZOKU_AUTH_USERNAME, and KAIZOKU_AUTH_PASSWORD before starting Compose.
For a local installation, install Python 3.12+, Node.js/npm, ffmpeg, and openssl, then run:
npm ci
./kaizoku
Keep .kaizoku/, backup/, downloads, and Jellyfin library folders when updating. .kaizoku/ contains configuration, watchlists, queue history, and other persistent state.
On the Queue page, choose 10, 25, 50, or 100 items per page beside the Previous and Next buttons. In Config → Watchlist management, use each list's Refresh checkbox to choose which lists are included in manual and scheduled bulk refreshes, then save the configuration. Watching and Planned are selected by default; custom lists can also be selected.
VPS login and Nginx Proxy Manager
Set these values in the .env file beside docker-compose.yaml before starting the container:
KAIZOKU_ALLOW_REMOTE=1
KAIZOKU_BASE_URL=https://tools.coreplay.eu/kaizoku
KAIZOKU_AUTH_USERNAME=your-admin-name
KAIZOKU_AUTH_PASSWORD=replace-with-a-long-unique-password
Keep .env private. Use Config → General to set the public base URL and login credentials instead, or edit base_url, auth_username, and auth_password in .kaizoku/config.json with Kaizoku stopped. Environment values take precedence. Config passwords are converted to salted scrypt hashes when settings are saved; a blank password field keeps the saved password. You can use /kaizoku as the base URL when the proxy supplies the public Host and X-Forwarded-Proto headers; the full HTTPS URL is recommended.
In Nginx Proxy Manager, use a proxy host for tools.coreplay.eu with a valid TLS certificate and Force SSL enabled. Add a Custom location /kaizoku pointing to Kaizoku's container/host on port 8421 over HTTP. Forward the request URI unchanged: no prefix stripping, rewrite, or trailing URI on proxy_pass is needed. Other locations on the domain can keep their existing backends. The equivalent Nginx location is:
location /kaizoku {
proxy_pass http://kaizoku:8421;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
Open https://tools.coreplay.eu/kaizoku/ and sign in. /kaizoku redirects to /kaizoku/; paths outside the mount return 404. After changing the base URL, reopen the app at the new address. Keep the backend port reachable only by the proxy (for example, on their shared Docker network or behind the VPS firewall).
Troubleshooting local login and Nginx Proxy Manager
For an explicitly private-interface container binding such as 192.168.1.10:8231:8421, use http://SERVER_LAN_IP:8231/kaizoku/ directly and https://tools.coreplay.eu/kaizoku/ through the proxy. Keep KAIZOKU_BASE_URL=/kaizoku if both addresses must work. A full HTTPS base URL fixes the expected login origin and enables Secure cookies, so direct HTTP login at a different host will not work with that setting. Credentials are case-sensitive; environment credentials override saved settings.
When Nginx Proxy Manager connects through the Docker host, its upstream must be the host's reachable LAN address on port 8231. When it shares a Docker network with Kaizoku, use kaizoku on port 8421. Verify the hostname carefully (for example, hade and hades are different hosts). For the published host port, the location should contain one copy of each header:
location /kaizoku {
proxy_pass http://SERVER_LAN_IP:8231;
proxy_set_header Host $http_host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Real-IP $remote_addr;
}
Replace SERVER_LAN_IP with the Docker host address. In Nginx Proxy Manager, edit the existing custom location's forwarding target and headers; avoid adding a second overlapping location. Keep proxy_pass without a trailing slash so the /kaizoku prefix reaches the app.
Test curl -i http://SERVER_LAN_IP:8231/kaizoku/ from the proxy host or container. A 401 response containing the sign-in form is expected before login and confirms that Kaizoku is reachable. A 404 at / is expected with this mount. A 502/504, connection refusal, timeout, or DNS error requires fixing the proxy's upstream address, network, or port before troubleshooting credentials. Check docker logs --tail 100 kaizoku for startup, permission, or session-write errors if the correct local login URL still fails.
After changing Compose environment values, run docker compose up -d --force-recreate kaizoku; a container restart alone does not apply them. Keep all existing volume mounts and their contents.
Configured credentials protect pages and APIs even when the proxy connects over loopback. A configured public base URL without credentials denies access. New sessions last 12 hours, survive restarts, and use path-scoped HttpOnly/SameSite=Strict cookies with Secure for HTTPS. Sign out revokes that browser's session; changing credentials revokes existing sessions. Login forms require a valid CSRF value and login attempts are limited to 10 per socket peer per 15 minutes (clients behind one proxy share this limit; limits reset on app restart). API clients can use HTTP Basic authentication over HTTPS; browser mutations must have the public same-origin Origin header. The /status endpoint (or /kaizoku/status with that mount path) always requires HTTP Basic authentication using the existing Kaizoku login configured under Config → General or through KAIZOKU_AUTH_USERNAME / KAIZOKU_AUTH_PASSWORD. It returns 200 OK with plain text OK followed by a newline; HEAD returns the same headers without a body. Missing or invalid Basic credentials return 401 with a Basic authentication prompt, even with a signed-in browser session. Without configured credentials it returns 503; remote requests also require KAIZOKU_ALLOW_REMOTE=1. Kaizoku currently supports one configured login, with no separate multi-user management. For an uptime monitor, select HTTP Basic authentication and enter that login. To test interactively, run curl --user YOUR_USERNAME https://mydomain.com/kaizoku/status and enter the password when prompted.
An existing local installation without credentials and without a public base URL retains local-only access. Updates preserve all existing volumes and state; reuse the same mounts when moving the instance to the VPS.
Documentation
See the Kaizoku wiki for detailed instructions:
- Setup and configuration
- Docker and Jellyfin
- Downloads and watchlists
- AI subtitles
- Data safety
- Providers and upstream versions
Provider parsers are adapted from TheYogMehta/extensions. Bundled active versions are Anikoto 7.0.0 and AnimePahe 7.0.1, checked against upstream revision 5a1de84ad651d088cf427655573a96500151d862 on 2026-10-27. Anikoto includes upstream metadata and stream-domain updates plus Kaizoku's filter search recovery, dub detection, encrypted sources, CDN variants, subtitle referers, and support for the site's current metadata layout. AnimePahe includes upstream metadata, title matching, ID resolution, and extension database updates while retaining official .pw, .com, and .org mirrors, bounded search retries, and bridge-compatible logging. Without a StrawVerse mapping database, Kaizoku keeps AnimePahe's UUID-based search IDs and existing episode URLs so existing watchlists and queued jobs remain compatible. Browser and mapping lifecycle hooks stay inactive in Kaizoku's short-lived bridge.
Upstream retired AniNeko on 2026-10-26. Its final 4.0.0 adapter remains available for compatibility with existing instances; provider selectors and Config's update status identify it as retired. It is no longer treated as a pending upstream update. Existing provider settings, watchlists, queue history, downloads, and thumbnails are preserved.
Live checks on 2026-10-27 confirmed Anikoto search, metadata, 12 episode entries with sub/dub availability, and a resolved dub source with eight subtitle tracks for The Iceblade Sorcerer Shall Rule the World. AniNeko returned HTTP 522, and all three AnimePahe mirrors returned HTTP 403 from the test host. Updating provider code does not remove those external service restrictions. Kaizoku does not host media.