ZiChuanLan/freebie-radar

What It Does

Resource Radar is a self-hosted aggregation and push workbench for community information. It collects items from developer forums, game stores, software giveaway sites, GitHub, Reddit, Bluesky, Telegram channels and custom RSS feeds, then runs each item through rule-based filtering, optional AI semantic grading and channel-based presentation before routing it to Telegram.

Every item is assigned a content kind (freebie, deal, opensource, info, noise), one of 21 categories, and an obtain method (free, conditional, lottery, trial, promo, paid). This keeps the default "true freebie" view separate from paid deals, carpool listings, second-hand trades and news. The README positions it for people who want to follow multiple interest channels (giveaways, VPS deals, open source, headlines) without manually checking dozens of sources. See the data source list and obtain classification for the taxonomy.

Quick Start

Docker Compose is the fastest path and does not require Node.js or a pre-made .env:

git clone https://github.com/ZiChuanLan/freebie-radar.git
cd freebie-radar
cp .env.example .env   # optional: ADMIN_TOKEN, Telegram, AI keys
docker compose up -d --build

The service listens on http://127.0.0.1:8788 by default. Verify it with:

curl http://127.0.0.1:8788/health

The response should contain "ok":true. An online demo is available for checking the UI without deploying.

For source runs, use Node.js 22.5+ and pnpm 10:

pnpm install
cp .env.example .env
pnpm build
pnpm start

pnpm dev runs the API on port 8788, and pnpm dev:web runs the Vite frontend on 5173 with a proxy to the API. Data is stored in ./data/radar.db by default.

If you need to collect from Cloudflare-protected sites such as LINUX DO, set FLARESOLVERR_URL=http://flaresolverr:8191 and start with docker compose --profile cf up -d --build.

Configuration and Operations

Most policy settings — AI model and prompt, blocking rules, push routes, quiet hours, source toggles and retention — are edited in the web admin panel at runtime. .env only needs process-level values: PORT, DATABASE_PATH, ADMIN_TOKEN, proxy variables, Telegram token and chat ID, AI endpoint keys, INGEST_TOKEN, GITHUB_TOKEN and scheduler flags.

Set a strong ADMIN_TOKEN before exposing the instance publicly; without it, the admin area is open. A GITHUB_TOKEN raises the GitHub collector limit from 60 to 5000 requests per hour.

A CLI is included for maintenance: pnpm tsx src/server/cli.ts sources lists sources and their last status, collect triggers a run, ai-review backfills unreviewed items, and reclassify re-runs rule-based classification without spending AI tokens.

Constraints and Privacy

• Runtime: Node.js 22.5+ for source runs; Docker path uses the bundled node:24-alpine image. SQLite is embedded, so no external database is needed.
• Login-gated sources: Zhihu, Xiaohongshu and Xiaoheihe require a persistent Chrome profile via scripts/pw-collect.mjs or the provided Tampermonkey script. The server does not store cookies or account credentials; the login profile stays in the local PROFILE_DIR.
• AI review: Optional, requires an OpenAI-compatible API endpoint; without it, rule-based classification and source-specific bypass rules still apply.
• Telegram push: Requires a bot token and chat ID. Push supports immediate and batched routes, a pre-push AI check, and a fallback mode when AI is unavailable.
• Scraping etiquette: The project asks users to respect target-site terms and keep fetch rates reasonable. It aggregates public pages and does not store or redistribute copyrighted content or account sharing.
• License: MIT.

HotRepo's take

The repository appeared on the new-project list on 2026-11-14, gaining 25 stars in the recorded one-hour window and reaching 127 stars with 27 forks. That is a single short snapshot, not a trend. What stands out technically is the scope of the self-hosted build: 63 built-in sources, a rule-plus-AI two-stage filter that skips blocked items before spending model tokens, six obtain-method levels, and multiple Telegram routes with pre-send re-checks. The README documents the Docker path and CLI clearly, but login-state collection still requires running a local Playwright script, and the AI and Telegram pieces depend on user-supplied credentials. For readers who want a tunable personal deal/news feed rather than a hosted service, the source and configuration depth are the main draw.