# Project pack: FreshRSS @ 9e38e2e

Facts about **FreshRSS** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v4.md). Pinned to one version; never changes after publication.

> FreshRSS is a self-hosted RSS and Atom reader. You subscribe to websites, blogs, podcasts and even pages without feeds, and read everything in one place with filters, labels, search and keyboard shortcuts. It is light enough for a small server and works with many phone apps.

## Setup path (checked 2026-11-03)
- **Start here, no Docker:** Run the source directly with the language runtime (PHP, Node or Python). No Docker.
- Offer Docker only if the person asks or this path fails. The commands further down may use Docker; they are not the starting point.
- Verdict source: https://raw.githubusercontent.com/FreshRSS/FreshRSS/HEAD/README.md
- You may be unable to download source archives or run commands in this session. The person downloads and runs things; if you cannot fetch something, give any changed file in full in chat with its path.

## Version and source
- Repository: https://github.com/FreshRSS/FreshRSS
- Pinned commit: `9e38e2e405aa6276697493c0b4c4f64e3c734e22`. Use exactly this version.
- Zip the person can download in a browser: https://github.com/FreshRSS/FreshRSS/archive/9e38e2e405aa6276697493c0b4c4f64e3c734e22.zip
- Fresh checkout (only if you have a shell and git): use the commands below in an empty folder. If this exact source is already checked out, keep your branch and use the development command; do not clone again or reset local changes.
- Official docs: https://freshrss.github.io/FreshRSS
- Live demo: https://demo.freshrss.org/i/. Shared demo. Don't enter real data.
- Licence: **AGPL-3.0-only**. Free to use and change. If other people use your changed version, including over a network (for example a website you host for them), you must offer them your source code under the same licence. Using it privately for yourself or your household has no extra obligations.

## Commands from the pinned source
- Developer commands (they may use Docker):

  ```sh
  git clone https://github.com/FreshRSS/FreshRSS bespoke-freshrss
  cd bespoke-freshrss
  git checkout --detach 9e38e2e405aa6276697493c0b4c4f64e3c734e22
  # Prepare development requirements and local configuration first.
  php -S localhost:8080 -t ./p
  ```

- Separate trial of the current upstream release (not your changes; sample data and a separate data directory only):

  ```sh
  docker run -d --restart unless-stopped --log-opt max-size=10m -p 8080:80 -e TZ=Europe/Paris -e CRON_MIN=1,31 -v freshrss_data:/var/www/FreshRSS/data -v freshrss_extensions:/var/www/FreshRSS/extensions --name freshrss freshrss/freshrss
  # then open http://localhost:8080
  ```
- Tools these commands use: Docker for a trial, PHP 8.1+ with a web server for development
- Develop: `php -S localhost:8080 -t ./p`
- Test: `make test-all`
- Check/lint: `make lint`
- Stack: php, javascript (Minz (own PHP framework), vanilla JavaScript). Difficulty for a non-developer with an AI: **easy**. Plain PHP with its own small framework and no build step for the app. Extensions and themes are a folder with a few files, which makes it one of the easier apps to personalise.
- The project's own AI instructions, in the repository: `AGENTS.md`.
Personal data: **yes**. Stored in: A database (SQLite by default) in the data folder. Secrets are entered by the person, never in chat.

---
Later, only when a step needs it: [reference.md](https://handoff.bespokeai.software/p/freshrss/9e38e2e/r3/reference.md) (customisation points, must-keep-working, data and costs, coding conventions) · [hosting.md](https://handoff.bespokeai.software/p/freshrss/9e38e2e/r3/hosting.md) (long-term hosting; hosts are paid third parties) · [bespoke.yaml](https://handoff.bespokeai.software/p/freshrss/9e38e2e/r3/bespoke.yaml) · [SKILL.md](https://handoff.bespokeai.software/p/freshrss/9e38e2e/r3/SKILL.md)