{"id":21962219,"url":"https://github.com/orangecoding/fredy","last_synced_at":"2026-06-11T08:00:52.645Z","repository":{"id":37981832,"uuid":"117512926","full_name":"orangecoding/fredy","owner":"orangecoding","description":"❤️ Fredy - [F]ind [R]eal [E]state [D]amn Eas[y] - Fredy keeps searching for new apartments, houses, and flats in Germany on platforms like ImmoScout24, Immowelt, Immonet, eBay Kleinanzeigen, and WG-Gesucht and instantly delivers the results to you via Slack, Telegram, Email, Discord or ntfy, so you can focus on the more important things in life ;)","archived":false,"fork":false,"pushed_at":"2026-06-10T15:12:47.000Z","size":35964,"stargazers_count":1145,"open_issues_count":4,"forks_count":169,"subscribers_count":8,"default_branch":"master","last_synced_at":"2026-06-10T16:21:51.995Z","etag":null,"topics":["appartment","appartments","crawler","ebay-kleinanzeigen","fredy","immobilien","immobilienscout24","immonet","immoscout24","immowelt","nodejs","puppeteer","real-estate","real-estate-search","self-hosted","telegrambots","web-scraping","wg-gesucht","wohnungssuche"],"latest_commit_sha":null,"homepage":"https://fredy.orange-coding.net/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/orangecoding.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["orangecoding"]}},"created_at":"2018-01-15T07:39:00.000Z","updated_at":"2026-06-10T15:19:13.000Z","dependencies_parsed_at":"2023-01-30T00:45:44.058Z","dependency_job_id":"213dbe5e-ef56-4f63-a7f1-5e65846c4d90","html_url":"https://github.com/orangecoding/fredy","commit_stats":null,"previous_names":[],"tags_count":207,"template":false,"template_full_name":null,"purl":"pkg:github/orangecoding/fredy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orangecoding%2Ffredy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orangecoding%2Ffredy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orangecoding%2Ffredy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orangecoding%2Ffredy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/orangecoding","download_url":"https://codeload.github.com/orangecoding/fredy/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orangecoding%2Ffredy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34188272,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["appartment","appartments","crawler","ebay-kleinanzeigen","fredy","immobilien","immobilienscout24","immonet","immoscout24","immowelt","nodejs","puppeteer","real-estate","real-estate-search","self-hosted","telegrambots","web-scraping","wg-gesucht","wohnungssuche"],"created_at":"2024-11-29T10:35:41.700Z","updated_at":"2026-06-11T08:00:52.638Z","avatar_url":"https://github.com/orangecoding.png","language":"JavaScript","funding_links":["https://github.com/sponsors/orangecoding"],"categories":["JavaScript"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n\n\u003ca href=\"https://fredy.orange-coding.net/\"\u003e\n\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://github.com/orangecoding/fredy/blob/master/doc/logo_white.png\" width=\"400\"\u003e\n  \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://github.com/orangecoding/fredy/blob/master/doc/logo.png\" width=\"400\"\u003e\n  \u003cimg alt=\"Jetbrains Open Source\" src=\"https://github.com/orangecoding/fredy/blob/master/doc/logo.png\"\u003e\n\u003c/picture\u003e\n\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://fredy.orange-coding.net/\" target=\"_blank\"\u003eWebsite\u003c/a\u003e\u0026nbsp;\u0026nbsp;|\u0026nbsp;\u0026nbsp;\n  \u003ca href=\"https://fredy-demo.orange-coding.net/\" target=\"_blank\"\u003eDemo\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/orangecoding/fredy/actions/workflows/test.yml/badge.svg\" alt=\"Tests\" /\u003e\n  \u003cimg src=\"https://github.com/orangecoding/fredy/actions/workflows/docker.yml/badge.svg\" alt=\"Docker\" /\u003e\n  \u003cimg src=\"https://github.com/orangecoding/fredy/actions/workflows/check_source.yml/badge.svg\" alt=\"Source\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fghcr-badge.elias.eu.org%2Fapi%2Forangecoding%2Ffredy%2Ffredy\u0026query=%24.downloadCount\u0026label=Docker%20Pulls\" alt=\"Docker Pulls\" /\u003e\n\u003c/p\u003e\n\n\n\n# Fredy 🏡 - Your Self-Hosted Real Estate Finder for Germany\n\nFinding an apartment or house in Germany can be stressful and\ntime-consuming.\\\n**Fredy** makes it easier: it automatically scrapes **ImmoScout24,\nImmowelt, Immonet, eBay Kleinanzeigen, and WG-Gesucht** and notifies you\ninstantly via **Slack, Telegram, Email, ntfy, discord and more** when new\nlistings appear.\n\nWith a modern architecture, Fredy provides a **clean Web UI**, removes\nduplicates across platforms, and stores results so you never see the\nsame listing twice.\n\n------------------------------------------------------------------------\n\n## ✨ Key Features\n\n-   🏠 Scrapes **ImmoScout24, Immowelt, Immonet, eBay Kleinanzeigen,\n    WG-Gesucht**\n-   ⚡ Instant notifications: Slack, Telegram, Email (SendGrid,\n    Mailjet), ntfy, discord \n-   🔎 Uses the **ImmoScout Mobile API** (reverse engineered)\n-   🌍 Runs anywhere: Docker, Node.js, self-hosted\n-   🖥️ Intuitive **Web UI** to manage searches\n-   🎯 Easy to use thanks to a user-friendly Web UI\n-   🔄 Deduplication across platforms\n-   ⏱️ Customizable search intervals\n\n------------------------------------------------------------------------\n\n## 🤝 Sponsorship [![](https://img.shields.io/static/v1?label=Sponsor\u0026message=❤\u0026logo=GitHub\u0026color=%23fe8e86)](https://github.com/sponsors/orangecoding)\n\nI maintain Fredy and other open-source projects in my free time.\\\nIf you find it useful, consider supporting the project 💙\n\nFredy is proudly backed by the **JetBrains Open Source Support Program**.   \n\n\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://www.jetbrains.com/company/brand/img/logo_jb_dos_3.svg\"\u003e\n  \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://resources.jetbrains.com/storage/products/company/brand/logos/jetbrains.svg\"\u003e\n  \u003cimg alt=\"Jetbrains Open Source\" src=\"https://resources.jetbrains.com/storage/products/company/brand/logos/jetbrains.svg\"\u003e\n\u003c/picture\u003e\n\n------------------------------------------------------------------------\n\n## 👨‍🏫 Demo\nYou can try out Fredy here: [Fredy Demo](https://fredy-demo.orange-coding.net/)\n\n------------------------------------------------------------------------\n\n## 🚀 Quick Start\n\n### With Docker\n\n\u003e [!NOTE]\n\u003e In order to start Fredy, you must provide a config.json. As a start, use the one in this repo: https://github.com/orangecoding/fredy/blob/master/conf/config.json\n\n``` bash\ndocker run -d --name fredy \\\n  -v fredy_conf:/conf \\\n  -v fredy_db:/db \\\n  -p 9998:9998 \\\n  ghcr.io/orangecoding/fredy:master\n```\n\nLogs:\n\n``` bash\ndocker logs fredy -f\n```\n\n### Manual (Node.js)\n\n-   Requirement: **Node.js 22 or higher**\n-   Install dependencies and start:\n\n``` bash\nyarn\nyarn run start:backend   # in one terminal\nyarn run start:frontend  # in another terminal\n```\n\n👉 Open \u003chttp://localhost:9998\u003e\n\n### With Unraid\n\nShould you use [Unraid](https://unraid.net/), you can now install Fredy from the community store :)\n\n**Default Login:**\n- Username: `admin`\n- Password: `admin`\n\n------------------------------------------------------------------------\n\n## 📸 Screenshots\n\n| Fredy Maps View                                  | Dashboard                                               | Found Listings                                                              |\n|--------------------------------------------------|-----------------------------------------------------------------------|-----------------------------------------------------------------------------|\n| ![Screenshot showing Fredy](doc/screenshot1.png) | ![Screenshot showing job configuration in Fredy](doc/screenshot3.png) | ![Screenshot showing found listings in Fredy](doc/screenshot2.png) |\n\n------------------------------------------------------------------------\n\n## 🧩 Core Concepts\n\nFredy is built around three simple concepts:\n\n### Provider 🌐\n\nA **provider** is a real-estate platform (e.g. ImmoScout24, Immowelt,\nImmonet, eBay Kleinanzeigen, WG-Gesucht).\\\nWhen you create a job, you paste the search URL from the platform into\nFredy.\\\n⚠️ Always make sure the search results are sorted by **date**, so Fredy\npicks up the newest listings first.\n\n### Adapter 📡\n\nAn **adapter** is the channel through which Fredy notifies you (Slack,\nTelegram, Email, ntfy, discord ...).\\\nEach adapter has its own configuration (e.g. API keys, webhook URLs).\\\nYou can use multiple adapters at once --- Fredy will send new listings\nthrough all of them.\n\n### Job 📅\n\nA **job** combines providers and adapters.\\\nExample: \"Search apartments on ImmoScout24 + Immowelt and send results\nto Slack + Telegram.\"\\\nJobs run automatically at the interval you configure (see\n`/conf/config.json`).\n\n### MCP Server 🤖\n\nStarting with **V20**, Fredy ships with a built-in **MCP Server **. This allows you to connect Fredy to LLMs (like Claude, ChatGPT, or local models via LM Studio) and query your real estate data using natural language.\nThe local LLM can even enrich existing listings by checking the listing online.   \n\nFor more information on how to set it up and use it, please refer to the [MCP Readme](lib/mcp/README.md).\n\n------------------------------------------------------------------------\n\n## Immoscout\n\nImmoscout has implemented advanced bot detection. In order to work around this, we are using a reversed engineered version of their mobile api. See [Immoscout Reverse Engineering Documentation](https://github.com/orangecoding/fredy/blob/master/reverse-engineered-immoscout.md)\n\n## 🛡️ Bot Detection \u0026 Proxies\n\nMost browser-based providers (immowelt, immonet, kleinanzeigen, ...) are scraped through a hardened headless browser ([CloakBrowser](https://www.npmjs.com/package/cloakbrowser)). It makes the **browser fingerprint** indistinguishable from a real Chrome, which is enough when you run Fredy on a normal home connection.\n\nOn a **server / VPS the requests usually originate from a datacenter IP**, and providers behind anti-bot systems (e.g. AWS CloudFront/WAF) block those based on **IP reputation alone**, no matter how perfect the fingerprint is. The typical symptom: it works locally but you get `We have been detected as a bot :-/` on the server.\n\n### The fix: a residential proxy\n\nA **residential proxy** routes Fredy's browser through the internet connection of a real household, so the provider sees a \"normal user\" IP instead of a datacenter. For German portals, use a **German (DE) residential** (or mobile/4G) proxy. Plain VPNs and **datacenter proxies do not help** here, they share the same bad reputation as your server.\n\n**Configure it** under **Settings → Execution → Proxy URL**. Supported formats:\n\n```\nhttp://user:pass@host:port\nsocks5://user:pass@host:port\n```\n\nLeave the field empty to disable. The proxy applies to all headless-browser providers and takes effect on the next job run (no restart needed). Immoscout uses a separate mobile API and is not affected.\n\n### Where to get a residential proxy\n\nResidential proxies are a paid service (usually billed per GB, Fredy's traffic is small). Well-known providers offering German residential IPs include:\n\n| Provider | Notes |\n|---|---|\n| [IPRoyal](https://iproyal.com) | Pay-as-you-go, no monthly minimum, good for low volume |\n| [Webshare](https://www.webshare.io) | Cheap entry tier, has a small free plan to test with |\n| [Decodo (formerly Smartproxy)](https://decodo.com) | Easy setup, country/city targeting |\n| [SOAX](https://soax.com) | Residential + mobile, fine-grained geo-targeting |\n| [Bright Data](https://brightdata.com) | Largest pool, most features, higher complexity/price |\n| [Oxylabs](https://oxylabs.io) | Enterprise-grade, larger plans |\n\nThis is not an endorsement, pick whatever fits your budget. For low-volume use like Fredy, a pay-as-you-go plan (e.g. IPRoyal) or a cheap entry tier (e.g. Webshare) is usually plenty. Make sure to select **Germany** as the proxy location and keep the search interval reasonable (the higher the interval, the less you look like a bot).\n\n## Analytics\n\nFredy is completely free (and will always remain free). However, it would be a huge help if you’d allow me to collect some analytical data.\nBefore you freak out, let me explain...  \nIf you agree, Fredy will send a ping once every 6 hours to my internal tracking project (Will be open sourced soon).  \nThe data includes: names of active adapters/providers, OS, architecture, Node version, and language. The information is entirely anonymous and helps me understand which adapters/providers are most frequently used.\u003c/p\u003e\n\n**Thanks**🤘\n\n## 🐞 Debug Information\n\nSince Fredy **22.5.0** there is a built-in way to capture everything Fredy logs into the\ndatabase for a limited time and download it as a single zip file. This is the recommended\nway to attach diagnostics to a bug report. I decided against simply putting all logs into\na debug bundle due to privacy reasons!\n\n**How it works**\n\n- Debug logging is **opt-in** and admin-only. As long as it is off, Fredy behaves exactly\n  as before (console output only, nothing in the DB).\n- When you turn it on, every log line (`debug`, `info`, `warn`, `error`) is additionally\n  written into the `debug_logs` SQLite table. The console keeps logging at its usual level.\n- The recorded data is hard-capped at **5 MiB** via a rolling buffer: once the cap is hit,\n  the oldest entries are dropped automatically so the newest ones always survive.\n- The on/off flag is persisted, so debug logging stays on across restarts (and you'll see\n  the warning banner everywhere until you turn it off again).\n\n**Capturing a debug bundle**\n\n1. Open Fredy as an **admin** and go to **Settings → Debug**.\n2. Click **\"Enable debug logging\" / \"Debug-Logging aktivieren\"**. A red banner appears on\n   every page while recording is on.\n3. **Reproduce the bug**.\n4. Come back to **Settings → Debug** and check the progress bar, if it stayed at 0 %,\n   nothing was captured.\n5. Click **\"Download debug information\" / \"Debug Informationen herunterladen\"**. You get a\n   zip named `YYYY-MM-DD-FredyDebug-\u003cversion\u003e.zip` containing two files:\n   - `logs.txt` - every log line captured while recording was on, prefixed with timestamp\n     and level.\n   - `sys.txt` - runtime snapshot (Fredy version, Node.js version, OS, Docker detection,\n     CPU, memory, sanitized settings). Proxy credentials and session secrets are\n     **stripped** before export.\n6. Attach the zip to the bug report.\n7. Optional but recommended: click **\"Disable debug logging\"** to stop recording, and\n   **\"Delete stored debug logs\"** once you've sent the zip so the DB does not keep them\n   around.\n\n**What is _not_ included**\n\n- passwords/privacy relevant things\n- Anything that Fredy itself does not pass through its `logger`. If a third-party library\n  writes directly to `process.stderr`, that output stays on the console only.\n\n## 🛠️ Development\n\n### Development Mode\n\n``` bash\nyarn run start:backend:dev\nyarn run start:frontend:dev\n```\nYou should now be able to access _Fredy_ from your browser. Check your Terminal to see what port the frontend is running on.\n\n### Run Tests\n\n## \"Online\" tests\nThese tests are directly executed against the actual providers.\n``` bash\nyarn run test\n```\n\n## \"Offline\" tests\nThese tests are using the test fixtures instead of the actual providers. Much faster and \"good enough\" to test the core functionality.\n``` bash\nyarn run test:offline\n```\n\n## Download new fixtures\nIf you have to refresh the fixtures (every once in a while needed because the providers change their code), run this command:\n``` bash\nyarn run download-fixtures\n```\n\n## Adding a new language\n\nFredy's UI is fully multilingual. Translation files live in `ui/src/locales/`. To add a new language, create a single JSON file there, no code changes required.\n\n**Example: `ui/src/locales/fr.json`**\n```json\n{\n  \"_meta\": {\n    \"flag\": \"🇫🇷\",\n    \"name\": \"Français\",\n    \"locale\": \"fr-FR\",\n    \"semiLocale\": \"fr\"\n  },\n  \"nav.dashboard\": \"Tableau de bord\",\n  \"common.save\": \"Enregistrer\",\n  ...\n}\n```\n\nThe `_meta` fields:\n\n| Field | Description |\n|---|---|\n| `flag` | Unicode flag emoji shown in the language selector |\n| `name` | Display name shown in the language selector |\n| `locale` | BCP 47 locale string used for date and number formatting (e.g. `fr-FR`) |\n| `semiLocale` | Semi UI locale key for component-level strings (date pickers, pagination, etc.) |\n\n\u003e **Important:** `semiLocale` must exactly match a locale filename from the Semi UI locale sources (without the `.js` extension). See the [available Semi UI locales on GitHub](https://github.com/DouyinFE/semi-design/tree/main/packages/semi-ui/locale/source) for the full list of supported keys.\n\nAfter adding the file, rebuild the frontend (`yarn build:frontend` or restart the dev server) and the new language will appear automatically in **Settings → User Settings → Language**.\n\n------------------------------------------------------------------------\n\n## 📐 Architecture\n\n``` mermaid\nflowchart TD\n subgraph Jobs[\"Jobs\"]\n        A1[\"Job 1\"]\n        A2[\"Job 2\"]\n        A3[\"Job 3\"]\n  end\n subgraph Providers[\"Providers\"]\n        C1[\"Provider 1\"]\n        C2[\"Provider 2\"]\n        C3[\"Provider 3\"]\n  end\n subgraph NotificationAdapters[\"Notification Adapters\"]\n        F1[\"Adapter 1\"]\n        F2[\"Adapter 2\"]\n  end\n\n    A1 --\u003e B[\"FredyPipelineExecutioner\"]\n    A2 --\u003e B\n    A3 --\u003e B\n    B --\u003e C1 \u0026 C2 \u0026 C3\n    C1 --\u003e D[\"Similarity Check\"]\n    C2 --\u003e D\n    C3 --\u003e D\n    D --\u003e E{\"Duplicate?\"}\n    E -- No --\u003e F1\n    F1 --\u003e F2\n```\n\n------------------------------------------------------------------------\n## 🤖 Using AI such as Claude Code\nWhen I started building Fredy, LLMs were still basically the wet dream of a few nerdy scientists.\n\nNowadays, it’s easier than ever to throw a prompt into the LLM of your choice and let 'the AI' build your stuff. I’m not against that. I use Claude Code myself for smaller tasks, and I do think these tools can be really useful.\n\nThat said, I still believe humans should stay in charge. AI is great-ish at writing code, but it still lacks creativity, context, and the ability to see the full picture.\n\nSo, if you want to contribute to Fredy, using AI tools to get things done is totally fine. Just please don’t stop thinking.\n\nI’ve had one too many PRs full of hallucinated bullshit.\n\n**Thanks ;)**\n\n------------------------------------------------------------------------\n\n## 👐 Contributing\n\nThanks to everyone who has contributed!\n\n\u003ca href=\"https://github.com/orangecoding/fredy/graphs/contributors\"\u003e\u003cimg src=\"https://contrib.rocks/image?repo=orangecoding/fredy\" /\u003e\u003c/a\u003e\n\nSee the [Contributing\nGuide](https://github.com/orangecoding/fredy/blob/master/CONTRIBUTING.md).\n\n------------------------------------------------------------------------\n\n## ⭐ Star History\n\n[![Star History\nChart](https://api.star-history.com/svg?repos=orangecoding/fredy\u0026type=Date)](https://www.star-history.com/#orangecoding/fredy\u0026Date)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forangecoding%2Ffredy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Forangecoding%2Ffredy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forangecoding%2Ffredy/lists"}