Stowarr

Watch your precious cargo. Stow it smarter.

Automatically optimize watched media to reclaim storage without sacrificing quality.

Status: v0.1.0-alpha / read-only

Stowarr currently observes media state, evaluates lifecycle eligibility, and scores replacement candidates. Downloads, imports, replacements, and deletions are not yet enabled.

What is Stowarr?

Stowarr is a lifecycle-aware storage optimizer for self-hosted media libraries using Jellyfin, Sonarr, and Radarr.

The intended workflow is:

1. Detect when media has been watched.
2. Wait a configurable grace period.
3. Inspect the existing file and storage cost.
4. Evaluate smaller acceptable replacements.
5. Estimate potential storage savings.
6. Request approval.
7. Acquire the replacement through Sonarr or Radarr.
8. Verify the successful import.
9. Only then allow the original media to be retired.
10. Report actual storage saved.

The observation and policy layers remain read-only toward media services. An optional private approval queue records staging decisions locally; execution is still disabled. See Staging approvals for setup.

Safety First

Existing media must never be removed before its replacement has been successfully downloaded, imported, and verified.

Current safety rules include:

• Jellyfin Played=true determines watched state.
• Missing or uncertain completion history fails safe.
• Default watched delay is 30 days.
• Minimum replacement resolution is 1080p.
• Remux, raw-HD, BR-DISK, CAM, and telesync candidates are rejected.
• HEVC / x265 / H.265 is preferred.
• Candidates must save at least 5 GiB OR 40%.
• Source-service synchronization is read-only.
• Download, import, and delete capabilities remain disabled.
• Initial write-enabled workflows will require explicit approval.
• Optional staging approvals pin the exact source/release and expire after 72 hours.

Current Features

• Jellyfin watched-state inventory
• Sonarr season correlation
• Radarr movie inventory
• TV season completeness detection
• Persistent SQLite state
• Stable identity keys
• Schema versioning
• Private approval UI with Approve staging / Reject buttons
• Durable release-specific decisions and email/webhook link notifications
• Audit-log foundation
• Lifecycle safety engine
• 30-day eligibility policy
• Replacement candidate scoring
• Storage-savings calculations
• Unprivileged Docker runtime
• Secret-safe configuration
• SQLite-safe backups
• Automated validation and unit tests

Not Yet Enabled

• Release searching
• Downloads
• Replacement imports
• Media deletion
• Telegram approval
• Automatic optimization

Validation

Run:

./scripts/validate.sh

All tests and safety checks must pass before changes are committed.

Security

Never commit API keys, passwords, tokens, or other credentials.

Runtime credentials are supplied through environment variables and local configuration files excluded from Git.

See SECURITY.md for vulnerability reporting guidance.

License

MIT