FLINCH 0.2.0

Log in with a username and password

• The web UI now uses a username and password (FLINCH_WEB_USERNAME, FLINCH_WEB_PASSWORD), like Sonarr's and Radarr's login, instead of a token pasted into the browser. The browser keeps no secret. (#20)
• FLINCH_WEB_TOKEN stays as the API key. Authorization: Bearer still works on every route, POST /v1/systemone included, and X-Api-Key now does too. Home Assistant, n8n and scripts need no change.
• Sessions use an HttpOnly, SameSite=Strict cookie (Secure behind HTTPS) that lasts 30 days, with Log out in the header. Writes need the UI's own header, failed logins pause after 5 tries, and credentials never reach responses or logs.

Safer deletion decisions

• Adopting a fitted model can no longer widen what may be deleted. The P(safe) the floors and the eviction order read is capped at the hand-set priors. (#14)

• A movie counts as watched only when Plex counted a view. A lastViewedAt stamp alone means started, and a started movie or season is never scored as more deletable than a finished one. (#15)

• Nothing unwatched is handed to a delete collection.

  • A blank Leaving Soon title now holds unwatched items, and never-played reclaim with them, instead of sending them straight to deletion.
  • An unwatched item waiting to enter Leaving Soon is taken out of any delete collection at once.
  • An unwatched item in a delete collection FLINCH did not add it to is kept by an exclusion.

  The Capacity, Overview and Settings pages say when a hold applies. (#16)

• A moved eviction keeps its recycle-bin credit, and credit lost to a restart or a bad state file heals, so one gap is never evicted twice. (#17)

• No watch evidence means keep. An item no watch source reported on is never reclaimed as unplayed. (#18)

• An unreadable Tautulli percentage counts as unfinished. (#19)

• The docs say which floors actually gate deletion, and no longer claim a fitted model is running. (#13)

Known limit. One case can still delete without a warning: a season whose watched episodes were deleted outside FLINCH can read as completed. See Known limits in docs/how-it-works.md for the workaround.

Upgrade

Running latest? It now points at 0.2.0, and any restart pulls it. Pin 0.1.1 until you have done steps 1 and 2.

1. Add the login to flinch-secrets. Patch in FLINCH_WEB_USERNAME and FLINCH_WEB_PASSWORD; Upgrading from the access token shows a kubectl patch that keeps the password out of your shell history.
2. Apply the 0.2.0 manifests. Update your checkout (git fetch --tags && git checkout v0.2.0), set newTag: "0.2.0" in your overlay if you have one, and run kubectl apply -k. The 0.2.0 manifests pass the two new keys to flinch-web. Moving newTag alone in an overlay of a 0.1.1 checkout runs 0.2.0 on the old manifests, and the UI stays on "No login set".
3. Log in. Until the Secret has both keys and flinch-web runs the 0.2.0 manifests, the UI says "No login set". If you added the keys after the rollout, run kubectl -n media rollout restart deploy/flinch-web. Nothing is left open meanwhile, and the API key keeps working.

No state migration. Every behaviour change is toward keeping; these are the ones you may notice on the first cycle:

• With no Leaving Soon collection named, unwatched items and never-played reclaim are held.
• A movie read as watched only from Plex's view stamp, or only from Tautulli streams with no readable percentage, now counts as started: it waits for never-played reclaim and a Leaving Soon warning.
• An item no watch source reported on is kept.
• An unwatched item FLINCH put in a delete collection earlier is taken back out and moves to Leaving Soon. One in a delete collection FLINCH has no record of adding it to gets a FLINCH exclusion until you take it out.
• Adopting a fitted model can no longer make an item eligible that the hand-set priors hold.

POST /v1/systemone: safe is the forecast alone and ignores your keep rules; ask decision for the plan's verdict, and never delete on either. The endpoint changes nothing; only Maintainerr deletes.

docker pull ghcr.io/tobhoster/flinch:0.2.0   # amd64 and arm64

FLINCH 0.1.1

Fixes

• Response bodies are capped at 64 MiB. A broken or hostile Radarr, Sonarr, Plex, Tautulli or Maintainerr can no longer exhaust the daemon's memory with one answer. An oversized answer is a failed read, so the items it covers are held.
• POST /v1/systemone parses the snapshot once per version, off the async runtime, instead of re-reading items.json on every request.

UI

React 19, Vite 8 and framer-motion 13. Nothing looks or works differently.

Checked on every change

Nothing merges into main without the tests, CodeQL and the Security workflow: gitleaks over the history, cargo-deny (advisories, licenses, sources), npm audit with registry signatures, actionlint and zizmor, and Trivy plus a smoke test of the image run as the manifests run it. Release tags can no longer be moved or deleted.

Upgrade

Set newTag: "0.1.1" in deploy/kustomization.yaml (or your overlay) and run kubectl apply -k. Nothing else changes: no new settings, no state migration.

docker pull ghcr.io/tobhoster/flinch:0.1.1   # amd64 and arm64

FLINCH 0.1.0

The first public release of FLINCH: it keeps a Plex library under its disk ceiling, frees what nobody will miss first, and leaves the deleting to Maintainerr.

Install

docker pull ghcr.io/tobhoster/flinch:0.1.0   # amd64 and arm64

deploy/kustomization.yaml pins this release. The install guide walks through the Secret, the Maintainerr collections and turning on enforcement. Try it first with the demo:

docker run --rm -p 127.0.0.1:7911:7911 -e FLINCH_STATE_DIR=/tmp/demo -e FLINCH_WEB_TOKEN=demo \
  ghcr.io/tobhoster/flinch:0.1.0 sh -c 'flinch-demo && flinch-web'

Security

• The UI and its API need a token (FLINCH_WEB_TOKEN). Without one, the API refuses every request.
• The Ingress is opt-in (deploy/ingress) and HTTPS only.
• The pods run as a non-root user with a read-only root filesystem, no capabilities and the runtime's seccomp profile.
• The image comes with a build provenance attestation and an SBOM.

Report vulnerabilities privately; see SECURITY.md.