RSSMonster

A modern, self-hosted RSS reader that turns information overload into organized, explainable reading.

Documentation · Quick start · Features · Choose a deployment

!RSSMonster Reader Mode: navigation, article list, and selected article in a three-panel workspace

Why RSSMonster?

RSSMonster treats your feeds as a stream of signals rather than a pile of unread items. Keep the familiar feed inbox, then use intelligent organization to decide what deserves attention and how different reports fit together.

Follow a story without rereading every headline. Semantic Events collect

reporting about the same occurrence and let you expand its coverage. Duplicate handling separately identifies repeated content, preserving the distinction between a syndicated copy and another publisher's reporting.

Understand why something ranks highly. Recommended emphasizes your personal

interests; Top Stories surfaces current coverage with broad source support. Inspect the contributing signals, or choose chronological reading when you simply want to catch up.

Define your own reading views. Declarative Smart Folders turn advanced

search expressions into reusable selections. A project watchlist, today's unread articles, and a quality-focused research inbox can each have their own rules without moving articles between collections.

Read comfortably throughout the day. A three-panel desktop Reader, spacious

Expanded view, compact summaries, keyboard navigation, and mobile gestures support both quick scans and longer reading sessions.

Choose how much infrastructure you need. Start with SQLite for lightweight

personal reading, or use MySQL and optional local inference for semantic organization and background analysis. You control storage and provider choices.

See RSSMonster in action

The hero shows Reader Mode. These views show other ways to read and explore your library, including features available with inference enabled. Click or tap a screenshot to view it at full resolution. See reading modes for the controls and layout differences.

Scan or read in depth

Expanded Mode _{Read article content and compare story sources.}	Summarized Mode _{Scan short previews in a compact stream.}

Follow stories and interests

Events _{Inspect story coverage and broader themes.}	Interest Islands _{Explore recurring interests shaped by reading feedback.}

Read across devices

Landscape _{Keep navigation visible on wider screens.}	Portrait _{Read a focused stream with compact touch controls.}

Main capabilities

Reading

Use Reader, Expanded, or Summarized mode; Headlines offers a denser list, while Summary Bullets displays generated summaries when analysis is available. Bookmark articles, open original sources, and control when articles are marked read. Keyboard shortcuts, portrait bookmark swipes, and light, dark, or system themes support everyday reading.

Organization

Arrange subscriptions into categories, label articles with tags, and keep favorites for later. Feed item filters accept or exclude future entries per subscription. Automated actions apply regular-expression rules to bookmark, mark read, tag, hide, or override scores on matching incoming articles.

Search combines words, dates, article state, tags, and supported score or semantic filters. Save a query such as @today unread:true sort:desc as a Smart Folder; new matches appear automatically. Inference-backed score and semantic selections need the corresponding processing to be enabled and available.

Intelligence

Events connect reports about an occurrence; Interest Islands learn recurring personal interests from reading feedback. Related-article recommendations use semantic evidence, while expandable story sources keep alternative coverage accessible. Sparse evidence can legitimately produce no recommendations.

Recommended remains available for every eligible article even without an Island match: missing personal evidence is neutral. Interest uses confidence-aware direct Island paths and bounded explicit feedback; semantic labels explain results rather than establishing identity.

Scoring and Ranking documents Recommended, Top Stories, and Quality ordering. Article quality describes writing, tone, and promotional content; FeedTrust describes a subscribed source's recent value. These remain separate signals, and neither is factual verification.

The optional assistant supports conversational discovery and source-based answers about stored articles. It uses an OpenAI provider and is configured separately from local embeddings, summaries, tags, and scoring.

Self-hosting and compatibility

Run with SQLite or MySQL and keep accounts, subscriptions, and reading state scoped to each user. Move subscriptions with OPML import/export, or expose saved selections as private, tokenized generated RSS feeds. Fever and Google Reader compatibility connect supported client workflows; consult their documented contracts and limitations when choosing a client.

Choose a deployment

Run RSSMonster as a desktop app or host a server for access across devices. The screenshots showcase capabilities from the broader product; desktop mode and the SQLite quick start do not bundle inference models, but can connect to remote inference.

| Deployment | Best for | Included capabilities | | --- | --- | --- | | Desktop app (Electron) | Reading locally on Windows, macOS, or Linux | Existing reader with a local SQLite database and manual feed refresh. No Docker, separate server setup, worker processes, or scheduled crawling. Optional remote inference via Settings. | | SQLite quick start | Trying RSSMonster and lightweight personal reading | Web reader, scheduled crawling, search, subscriptions, and rule-based organization. No separate database service, bundled inference service, or AI worker. Optional remote inference via Settings or environment. | | Comprehensive MySQL deployment | Local intelligent processing, multiple active users, and higher write concurrency | MySQL 8.4, crawl and AI workers, Qwen embeddings and generation, and ModernBERT scoring for analysis, semantic organization, and recommendations. |

Install the Progressive Web App on supported devices to use an existing self-hosted RSSMonster server in its own app window, with optional Web Push for new articles. The PWA caches its shell; loading articles and saving reading state still require access to that server. The Electron desktop app runs its own backend and stores its data locally.

Saved search-based Smart Folders work in desktop mode and both server profiles. Choose the comprehensive profile for local classification, embeddings, scoring, semantic labels, Smart Folder recommendations, and feed rediscovery without an OpenAI API key. Desktop and SQLite can connect to an inference service through Settings → AI / Inference or INFERENCE_BASE_URL and an optional matching INFERENCE_API_KEY. Environment URLs take precedence and hide configuration controls; discovered capabilities remain visible. Background enrichment still requires an AI worker, which these lightweight profiles do not start. Provider/model settings remain inside inference. For model downloads, credentials, startup, and readiness checks, follow the MySQL deployment guide.

For self-hosting, database choice and inference settings are separate configuration concerns; SQLite and MySQL are the two supplied server profiles. Read database configuration and model usage before customizing a source installation.

Docker Quick Start

Have Git, Docker Engine or Docker Desktop, and Docker Compose available. The commands below use a POSIX shell and start the default SQLite profile.

1. Clone the repository.

git clone https://github.com/pietheinstrengholt/rssmonster.git
cd rssmonster

2. Create application secrets. Create an owner-only .env in the repository root:

touch .env
chmod 600 .env
openssl rand -hex 32

Run the OpenSSL command twice, then add the two different generated values to .env in place of these placeholders:

JWT_SECRET=replace-with-a-long-random-secret
FEVER_CREDENTIAL_SECRET=replace-with-a-different-long-random-secret

Keep these values private and stable across restarts; never commit the file. On systems without POSIX permissions, restrict access using the host's file access controls.

3. Start RSSMonster and create your account.

docker compose up -d

Open http://localhost:3000. Startup initializes the SQLite database and starts the web application and dedicated crawl worker. Create your first account, then add feeds or import an OPML subscription list. The first account becomes the administrator; see First Login.

Persistent data lives in the rssmonster-data Docker volume, mounted at /app/data. docker compose down stops the deployment while keeping data. **Do not use docker compose down -v unless you intend to delete the database volume.**

The application port binds to host loopback by default. Before exposing it to other machines, follow configuration and reverse-proxy guidance and configure HTTPS. See Getting Started for complete installation instructions, health checks, logs, and production setup.

Documentation

Use the documentation index to explore the complete guides.

| Topic | Guides | | --- | --- | | Installation and deployment | Getting Started, manual installation, macOS, Ubuntu, production deployment | | Configuration and storage | Server settings UI, Environment settings and reverse proxies, SQLite and MySQL, Backup and Restore | | Local inference and models | Inference administration, Model Usage, Assistant and MCP | | Finding and organizing articles | Search, Smart Folders, feed item filters, Actions | | Semantic architecture and rankings | How RSSMonster Works, implementation guide, Scoring, FeedTrust | | Notifications and integrations | Web Push, Fever API, Google Reader API | | Development and maintenance | Contributing, npm Commands, Server Jobs |

Contributing

Bug reports, documentation improvements, tests, and focused feature contributions are welcome. Read Contributing for development setup, validation, and pull requests. Describe reproducible issues and include your deployment profile so others can investigate the same behavior.

Credits and license

Created by Piethein Strengholt and contributors. Built with Node.js, Express, Vue 3, Sequelize, SQLite/MySQL, Bootstrap Icons, and feedsmith.

pietheinstrengholt/rssmonster: Modern, self-hosted RSS reader with smart folders, powerful search, and a clean three-pane reading experience. Built with Vue and Express.