🦦 FeedFerret
A self-hosted, multi-user RSS reader with a modern reading experience, power-user automation, and native client compatibility.
Self-hosted · Multi-user · PWA · Google Reader API · REST API + MCP · AGPL-3.0 License
✨ Features
- Modern Reader — multiple layouts, dark mode, configurable width, mobile swipe gestures, PWA install
- Feed Intelligence — automatic full-text extraction (Defuddle → Readability, +AI fallback) with clean Markdown or HTML rendering, per feed; build a feed from any web page that has no RSS (paste a listing URL → engine-validated selectors); optional self-hosted RSSHub (YouTube/Reddit/GitHub…) and changedetection.io ("any page as a change feed") connectors
- Per-Feed Control — fetch transparency + health, full-text mode, keyword content filters, image hiding, HTTP auth, reader/display overrides — all also settable over the API
- Power-User Extras — ⌘K command palette, copy article as Markdown, per-feed reader defaults, auto-mark-as-read rules, keyword alerts, outbound webhooks (HMAC-signed)
- Notifications — browser push, email digests, Telegram, Gotify, ntfy
- Native Client Support — Google Reader API (Reeder, NetNewsWire, FeedMe, ReadKit) and Fever API
- API-First — REST API v1 + MCP endpoint (39 tools) for AI agents (Claude, n8n, LangChain); everything the UI can do is controllable via API and by LLM — no feature is UI-only
- AI Summaries & Tagging (BYOK) — OpenAI, Anthropic, Gemini, OpenRouter, Ollama — keys stored encrypted, all strictly optional
- Flexible Auth — local accounts, magic link, Google/GitHub OAuth, Authelia OIDC, TOTP 2FA
- Self-Hosting Ready — three Docker Compose variants (minimal / default / ultimate), PostgreSQL or SQLite, Coolify-compatible, 5-minute setup
🚀 Quick Start
git clone https://github.com/moby3012/feedferret.git && cd feedferret
cp .env.example .env # set AUTH_SECRET, AUTH_URL, POSTGRES_PASSWORD
docker compose up -d --build
Open http://localhost:3000 and follow the setup wizard. Done.
Required .env values:
AUTH_SECRET="$(openssl rand -base64 32)" # keep stable across deploys
AUTH_URL="https://rss.example.com"
AUTH_TRUST_HOST=true
POSTGRES_PASSWORD="strong-random-password"
🐳 Deploy
Three ready-to-use Compose files ship in the repo — pick the one that matches what you need, no editing required:
| File | Database | Render sidecar | RSSHub | changedetection.io |
|---|
docker-compose.minimal.yaml | SQLite | ✗ | ✗ | ✗ |
docker-compose.yaml (default) | PostgreSQL | ✓ | ✗ | ✗ |
docker-compose.ultimate.yaml | PostgreSQL | ✓ | ✓ | ✓ |
docker compose -f docker-compose.minimal.yaml up -d --build # or .yaml / .ultimate.yaml
| Method | Command / Notes |
|---|
| Docker Compose | docker compose -f <file> up -d --build — see the table above for which file, or docs/self-hosting.md for the full comparison |
| Coolify | Use Docker Compose deployment type — point to repo root and one of the three files above, set env vars in the Coolify dashboard. Do not add a custom networks: block. See docs/self-hosting.md |
| Local dev | pnpm install && pnpm run dev (SQLite recommended, no Docker needed) |
Full guide including reverse proxy (Nginx, Caddy, Traefik), updates, and backup: docs/self-hosting.md
📚 Documentation
🛠 Tech Stack
Next.js 16 · React 19 · TypeScript 6 · Prisma 7 · PostgreSQL / SQLite · Tailwind CSS v4 · shadcn/ui · Auth.js v5 · next-intl · TanStack Query · Defuddle + @mozilla/readability (full-text) · markdown-it / turndown (Markdown)
📊 Status
Production ready. English + German UI (i18n via next-intl).
pnpm run build ✅ · pnpm run lint ✅ · tsc --noEmit ✅ · pnpm test ✅ · CI on every PR ✅
Since v1.1.1, the entire Feed Intelligence pillar shipped (auto full-text, page→feed builder, AI config proposal, AI auto-tagging, RSSHub + changedetection.io connectors, per-article AI extraction, the 4-tier anti-bot/heavy-fetch stack), and the REST API v1 + MCP endpoint grew to cover the complete feature set (MCP 28 → 39 tools) — see CHANGELOG.md for the full history. These land in the Unreleased section pending a version bump.
Next up ⭐: a Performance & UX Audit — making the app snappier, faster, and more pleasant — then the v1.2 Theming release. See docs/MASTER-ROADMAP.md for the consolidated, ordered backlog.
📄 License
GNU Affero General Public License v3.0 (AGPL-3.0)
You are free to use, fork, and contribute to FeedFerret. Any modified version — including one run as a hosted service — must be released under the same license with attribution. See LICENSE for the full terms.
For commercial use without the AGPL obligations, open a GitHub Discussion to inquire about a commercial license.
