NewsNest – self-hosted news reader that ranks stories by my interests

Developer lucifix published NewsNest, a self-hosted RSS and Atom news reader that uses Anthropic's Claude API to score each story on topic, importance and personal fit against a user-written interests file, with a default daily AI spending cap of $0.50. NewsNest groups coverage of the same event from multiple outlets into a single card, stores everything in one SQLite file, and ships as a multi-arch Docker image (linux/amd64 and linux/arm64) on GHCR and Docker Hub, running on port 3095. Without an API key the app still works, showing stories newest first, and it refuses all access unless a password is set.

A self-hosted news feed that learns what you care about. NewsNest gathers your RSS feeds into one calm stream, folds the same story from different outlets into a single card, and uses Claude to rank and summarise what matters to you. Website https://lucifix.github.io/newsnest/ · Features features · Quick start quick-start · How it works how-it-works · Configuration configuration · Development development | <sub Feed, ranked for you</sub | <sub Swipe to sort</sub | <sub Dark mode, automatically</sub | <sub Outlets and headlines are made up. Photos from Unsplash https://unsplash.com by Mohammad Rahmani https://unsplash.com/@afgprogrammer , Gabriella Clare Marino https://unsplash.com/@gabiontheroad and Amol Tyagi https://unsplash.com/@amoltyagi2 .</sub Checking a dozen news sites every day is slow, and most of what you see isn't for you. Algorithmic feeds fix that by learning what keeps you scrolling, which is not the same as what you want to read. NewsNest is the opposite deal. You choose the sources, you write down what interests you, and you can see why every story ranks where it does. It runs on your own machine, keeps everything in one SQLite file, and talks to the Anthropic API with your own key. - 📰 Your own sources. Any RSS or Atom feed, plus GitHub release feeds for software you run. Import an OPML file, or try new feeds on probation: they only earn a place in your feed once you read them. - 🧠 Ranked for you. Claude scores each story on topic, importance and personal fit against an interests file that you write yourself or have drafted from a few ratings. - 🧩 One story, not five. Coverage of the same event by several outlets is grouped into one card, and wide coverage lifts a story up. - ✨ Key points on demand. A one-line lede, a few bullets, a "why this matters to you" line, and a hint whether the full article is worth your time. - 👍 It learns from you. Likes, dislikes and opens shift what you see. Pick more about or less from for an outlet or topic, and review the weekly suggestions for your interests before they apply. - 🔎 No black box. Calibration mode shows every story with its scores and reasons, and Missed this lets you paste a link the feed should have shown you. - 🃏 Swipe to sort. A one-thumb deck to rate a backlog in minutes. - 💸 A hard spending cap. AI calls stop for the day when your budget is reached default $0.50 . Without an API key everything still works, and stories are shown newest first. - 📱 Installable and private. A mobile-first web app with light and dark themes that installs to your home screen. Password-protected, with a one-click database backup. - 🩺 Knows when a feed breaks. A status page and a /health endpoint report sources that fail or go silent. And more - Keyword watches that always surface a topic, plus mute and must-show keyword filters - Full-text search , saved stories, a read history and a day-by-day archive - Per-source daily caps, so a firehose feed can't drown out everything else - Summaries in the language of your choice You need Docker https://docs.docker.com/get-docker/ with Compose, and, for the AI features, an Anthropic API key https://console.anthropic.com/ . Pull the published image no clone needed, and the one to use for a Portainer stack , or build from source. Multi-arch linux/amd64 + linux/arm64 , so a Raspberry Pi or an ARM NAS works too : - GHCR: ghcr.io/lucifix/newsnest - Docker Hub: docker.io/lucifix/newsnest Paste this into Portainer Stacks → Add stack → Web editor or save it as docker-compose.yml anywhere. Only the password needs filling in: services: newsnest: image: ghcr.io/lucifix/newsnest:latest container name: newsnest restart: unless-stopped ports: - 3095:8080 environment: NEWSNEST PASSWORD: change-me required: with no password the app refuses all access ANTHROPIC API KEY: "" optional: enables ranking and summaries TZ: UTC your time zone, e.g. Europe/Ljubljana volumes: - newsnest-config:/config - newsnest-data:/data volumes: newsnest-config: newsnest-data: For the full file, with host folders you can open and edit instead of Docker volumes, use docker-compose.yml https://github.com/Lucifix/newsnest/blob/main/docker-compose.yml from this repo: mkdir newsnest && cd newsnest curl -fsSLO https://raw.githubusercontent.com/Lucifix/newsnest/main/docker-compose.yml curl -fsSL https://raw.githubusercontent.com/Lucifix/newsnest/main/.env.example -o .env mkdir -p config data so Docker doesn't create them as root edit .env: set NEWSNEST PASSWORD, and ANTHROPIC API KEY for AI docker compose up -d Update: docker compose pull && docker compose up -d . Set NEWSNEST IMAGE TAG in .env to pin a release such as 0.3.1 ; the default is latest . git clone https://github.com/Lucifix/newsnest.git && cd newsnest cp .env.example .env set NEWSNEST PASSWORD, and ANTHROPIC API KEY for AI mkdir -p config data so Docker doesn't create them as root docker compose up -d --build Update: git pull && docker compose up -d --build Open http://localhost:3095 http://localhost:3095 , log in with your password, and tap Set up my profile : 1. Say where you live. Your country and city tell Claude whose news is "big", and your time zone is picked up from the browser. 2. Add local news. NewsNest offers the local pack for your country Australia, Austria, Canada, Croatia, France, Germany, Italy, Slovenia, the United Kingdom and the United States so far , or add your own feeds under Local in Settings → Feeds . 3. Rate about 30 headlines , and Claude drafts your interests from them. On first start NewsNest copies a starter config.yaml https://github.com/Lucifix/newsnest/blob/main/config.example/config.yaml into config/ , with international news and tech feeds and no local ones. Change the feeds in Settings → Feeds , or edit the file. It is re-read on every run, so there is nothing to restart. Note The login is a single shared password over plain HTTP, which is fine on your home network. If you expose NewsNest to the internet, put it behind an HTTPS reverse proxy. php flowchart LR A "RSS / Atom feeds<br/ GitHub releases" -- B "Fetch &<br/ de-duplicate" B -- C "Group the same story<br/ across outlets" C -- D "Claude scores<br/ topic · importance · fit" D -- E "Rank<br/ score × freshness × what you like" E -- F "Your feed" F -- "likes · opens · ratings" -- E A 60-second loop fetches the sources that are due, scores new stories in batches, and writes key points for the ones above your threshold. Scoring uses a small, cheap model with prompt caching; the rarer jobs drafting your profile, the weekly suggestions use a stronger one. Both are configurable. What leaves your server: headlines and snippets, and for key points the article text, go to the Anthropic API using your key. Your feed list, ratings and database stay on your machine, and NewsNest itself sends no telemetry. Everything lives in the config/ folder, which is re-read on every run: | File | Purpose | |---|---| | config.yaml | Feeds, GitHub repos, watches, schedules, thresholds, models and the spending cap. Every option is explained in config.example/config.yaml https://github.com/Lucifix/newsnest/blob/main/config.example/config.yaml . | | interests.md | What you care about and what to skip. Written on the Profile page, or by hand. | | seed examples.md | About 20 example headlines marked + want or - don't want . | Edits made in the Settings pages are written back to config.yaml , comments included. Tip The example config comes with international feeds, no region and the time zone UTC . Set where you live in Settings → General country, city, time zone , and NewsNest offers your country's local pack. Sections. Every feed belongs to one section, and the sections are the tabs along the bottom of the feed. A new install starts with Local, World and Tech. In Settings → Feeds → Sections you can rename them, add your own Sports, Science, Cinema… , reorder them, and remove one its feeds and stories move to a section you pick . Local and World are built in: they can be renamed but not removed, and share the News tab. A section is a tab once it has a feed; at most four can be tabs, and any further section shows as a chip under For you . The list is the sections: key in config.yaml . A config.yaml from before sections were editable has none and keeps the old four Tech, Local, World, Lifestyle until you change them, so nothing needs migrating and the database is untouched. Note Once you edit sections, config.yaml has a sections: list that older NewsNest versions don't understand. To go back to an older image, restore the config.yaml.bak made by the last edit. Environment variables Set these in .env see .env.example https://github.com/Lucifix/newsnest/blob/main/.env.example . | Variable | Default | Purpose | |---|---|---| | NEWSNEST PASSWORD | – | Required. Password for the web UI. With none set, access is refused. | | ANTHROPIC API KEY | – | Turns on scoring, key points and the weekly suggestions. | | TZ | UTC | Container time zone logs . The app itself uses timezone from config.yaml . | | NEWSNEST PORT | 3095 | Port the web UI is published on. | | NEWSNEST CONFIG PATH | /opt/newsnest/config | Host folder for config.yaml and the profile files. | | NEWSNEST DATA PATH | /opt/newsnest/data | Host folder for the database. | | PUID / PGID | 1000 | User and group the container runs as. | | NEWSNEST LOG LEVEL | INFO | Log level. | | NEWSNEST SCHEDULER | on | Set to off to disable background fetching for development . | .env.example sets the two paths to ./config and ./data . Backup and restore Backup: open Settings → Install, backup & log out → Download database backup . It gives you a single consistent .db file with all stories, ratings and history, and it is safe to take while the app is running. Copy the config/ folder too: it holds your feeds and interests, which the download does not include. Restore: stop the container, put the backup in your data folder as newsnest.db , and start it again. With Docker volumes the Option A snippet , copy it in while the container is stopped: docker cp backup.db newsnest:/data/newsnest.db . Deploy with Portainer 1. Create the host folders, owned by the container user: sudo mkdir -p /opt/newsnest/config /opt/newsnest/data sudo chown -R 1000:1000 /opt/newsnest 2. Stacks → Add stack → Repository : use this repository's URL, reference refs/heads/main , compose path docker-compose.yml . 3. Add the environment variables NEWSNEST PASSWORD and ANTHROPIC API KEY . 4. Deploy. Portainer pulls the published image from ghcr.io ; nothing is built on your server. 5. Check http://<server :3095/health , then open http://<server :3095/ . To update, choose Pull and redeploy on the stack, with Re-pull image turned on. The config and database live in /opt/newsnest and survive redeploys. Install it as an app on your phone NewsNest is a progressive web app: it gets a home-screen icon, opens full screen, and keeps your most recent pages available offline. Browsers only offer to install over HTTPS , so open it through an https address, for example one served by a reverse proxy, rather than http://<server :3095 . - Android Chrome : menu → Install app , or Settings → Install inside NewsNest. - iPhone Safari : Share → Add to Home Screen . python3 -m venv .venv && .venv/bin/pip install -r requirements.txt pytest .venv/bin/python -m pytest run the tests NEWSNEST PASSWORD=dev NEWSNEST SCHEDULER=off .venv/bin/python -m newsnest the app on :8080 The first run copies config.example/ to ./config/ git-ignored . Two helpers are useful when adding or debugging sources: .venv/bin/python -m newsnest.spike --source <feed-id fetch one source and print parsed samples .venv/bin/python -m newsnest.runner --no-ai one fetch-and-store tick, without AI There is also a dev container with its own project name, port 3096 and the local ./config and ./data folders: docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build Project layout newsnest/ web.py FastAPI app: pages, settings, login, JSON endpoints runner.py the 60-second loop: fetch due sources, then the AI steps fetchers/ RSS/Atom and GitHub-releases fetchers pipeline.py store items, de-duplicate by URL, record source health grouping.py group the same story across outlets scoring.py AI scoring and the final score summaries.py key points, fetched from the article text feed.py ranking and the home feed profile .py interests, drafting, and the weekly suggestions discovery.py OPML import and sources on probation db.py SQLite schema and migrations templates/ Jinja templates static/ CSS, JS, fonts, icons config.example/ starter config, copied to config/ on first start tests/ pytest suite Planned work and known limits are tracked in TODO.md https://github.com/Lucifix/newsnest/blob/main/TODO.md . Bug reports, ideas and pull requests are welcome. Found a bug? Settings → About & report a bug in the app opens a new issue with your version filled in. Please open an issue first for anything big. Run python -m pytest and ruff check . before you send a PR CI runs the linter on every PR , and add a test for what you change. A local news pack for your country is an easy first PR: add a LocalPack to LOCAL PACKS in newsnest/packs.py https://github.com/Lucifix/newsnest/blob/main/newsnest/packs.py with 8 to 10 national outlets across the spectrum, each checked with newsnest.discovery.check feed https, working, posting in the last two weeks . MIT https://github.com/Lucifix/newsnest/blob/main/LICENSE , except the bundled fonts in newsnest/static/fonts/ https://github.com/Lucifix/newsnest/blob/main/newsnest/static/fonts : JetBrains Mono https://github.com/JetBrains/JetBrainsMono and Space Grotesk https://github.com/floriankarsten/space-grotesk are licensed under the SIL Open Font License 1.1 https://openfontlicense.org ; their license files sit next to the fonts.