kraken-mirror (0.1.0.dev20261029191256)

Published 2026-10-29 20:39:41 +01:00 by 8lackangel

To install the package using pip, run the following command:

pip install --index-url  kraken-mirror

For more information on the PyPI registry, see the documentation.

One-way, one-source-to-many-receivers media mirror (Kraken)

Kraken

Kraken is a self-hosted, one-way folder mirror for Linux. One source node keeps a library of files (typically large media: 1–80 GB videos and audio) and mirrors it to up to a handful of receiver nodes, usually at other sites. Receivers store plain files and folders you can use directly; no restore tool is needed. Source and receiver are roles per library, so one node can share some libraries and receive others at the same time. New here? Read the documentation index first.

Features:

Scheduled, reviewable sync. Changes go out in bounded plans that a receiver can check, approve or hold.
Verified, resumable transfers. Every chunk and every file is checked against a BLAKE3 hash computed at the source.
Protection against mistakes. Mass deletes or replacements, such as ransomware, are held for approval. Deleted files stay in a 30-day trash. A library halts if its disk isn't mounted.
Direct, encrypted connections between nodes, dialled by whichever side can reach the other, with human-approved registration (or pairing) and no certificate authority. A relay forwards registrations, helps nodes find each other when addresses change and finds folders by UUID; it never sees file contents or names.

Requirements

Rocky Linux 10 or Debian 13, x86_64 or arm64; on other x86_64 distributions with systemd and glibc 2.34 or newer (Rocky/RHEL 9, Debian 12, Ubuntu 22.04 and later) the self-extracting .run installer.
Library storage on a local filesystem at the source. Receivers use XFS, ext4, ZFS or btrfs.
One reachable TCP port (8741) on at least one side of each pair of nodes.
For running from source: Python 3.12 or 3.13.

Quick start

The standard setup is a relay, a source (the machine with the data) and a receiver (the machine that gets the copy). Install the package on each, then follow the getting-started guide: it starts the services and does the rest in the web UI, from creating the administrator to watching the first sync.

dnf install kraken-mirror kraken-mirror-selinux   # Rocky Linux 10 (repository: see the guide)
apt install kraken-mirror                         # Debian 13
sudo sh kraken-<version>-linux-x86_64.run         # other distributions (glibc 2.34 or newer)
systemctl enable --now kraken-relay               # on the relay host
systemctl enable --now kraken-node                # on the source and the receiver

Then open each node's web UI (http://127.0.0.1:8740/) right away: the first visitor creates the administrator.

CI publishes the packages to the project's Gitea package registry: a release for every v* tag (channels el10 and trixie/main) and a dev build for every push to master (el10-dev and trixie/dev); see installing. The relay also comes as a container image for a TLS reverse proxy such as Nginx Proxy Manager (packaging/docker/relay/). Packages are built locally with scripts/pkg/build.sh (see the developer manual). For development:

uv venv .venv --python 3.13
uv pip install --python .venv/bin/python -e . --group dev
scripts/ci-local.sh

Current state

Area	State
Specification	v2, with decisions and errata
Implementation	P0–P8 complete; P9 (seeding, backup and restore, recovery, scrub, production readiness) complete except the hardware benchmark (P9.7, on the owner's hardware); see the implementation plan
Tested platforms	RPM on Rocky Linux 10 (bundled Python 3.12.14, SELinux enforcing) and DEB on Debian 13 (bundled Python 3.13.5, AppArmor enforce), x86_64 in VMs; arm64 packages start and sync under emulation; pip on Python 3.12 and 3.13