Website | Demo

Fredy 🏡 - Your Self-Hosted Real Estate Finder for Germany

Finding an apartment or house in Germany can be stressful and time-consuming.
Fredy makes it easier: it automatically scrapes ImmoScout24, Immowelt, Immonet, eBay Kleinanzeigen, WG-Gesucht, and InBerlinWohnen and notifies you instantly via Slack, Telegram, Email, ntfy, discord and more when new listings appear.

With a modern architecture, Fredy provides a clean Web UI, removes duplicates across platforms, and stores results so you never see the same listing twice.

Fredy also knows what a place would cost you. Enter your financial situation once, your income, your living costs, what you have saved, and every listing is measured against it. Fredy tells you which ones you can comfortably afford, which would be a stretch, and which are out of reach, for renting and for buying alike. See Financing Calculator.

✨ Key Features

🏠 Scrapes ImmoScout24, Immowelt, Immonet, eBay Kleinanzeigen, WG-Gesucht, InBerlinWohnen
⚡ Instant notifications: Slack, Telegram, Email (SendGrid, Mailjet), ntfy, discord
🔎 Uses the ImmoScout Mobile API (reverse engineered)
🌍 Runs anywhere: Docker, Node.js, self-hosted
🖥️ Intuitive Web UI to manage searches
🎯 Easy to use thanks to a user-friendly Web UI
🔄 Deduplication across platforms
⏱️ Customizable search intervals
💶 Add your personal financial situation and see which listings you can actually afford, for renting and for buying

🤝 Sponsorship

I maintain Fredy and other open-source projects in my free time, if you find it useful, consider supporting the project ❤️

Support me on

Ko-Fi | Github

Fredy is proudly backed by the JetBrains Open Source Support Program.

👨‍🏫 Demo

You can try out Fredy here: Fredy Demo

🚀 Quick Start

With Docker

Note

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

docker run -d --name fredy \
  -v fredy_conf:/conf \
  -v fredy_db:/db \
  -p 9998:9998 \
  ghcr.io/orangecoding/fredy:master

Logs:

docker logs fredy -f

Manual (Node.js)

Requirement: Node.js 22 or higher
Install dependencies and start:

yarn
yarn run start:backend   # in one terminal
yarn run start:frontend  # in another terminal

👉 Open http://localhost:9998

With Unraid

Should you use Unraid, you can now install Fredy from the community store :)

Default Login:

Username: admin
Password: admin

📸 Screenshots

Fredy Maps View	Dashboard	Found Listings

🧩 Core Concepts

Fredy is built around three simple concepts:

Provider 🌐

A provider is a real-estate platform (e.g. ImmoScout24, Immowelt, Immonet, Deutsche Wohnen, eBay Kleinanzeigen, WG-Gesucht).
When you create a job, you paste the search URL from the platform into Fredy.
⚠️ Always make sure the search results are sorted by date, so Fredy picks up the newest listings first.

Adapter 📡

An adapter is the channel through which Fredy notifies you (Slack, Telegram, Email, ntfy, discord ...).
Each adapter has its own configuration (e.g. API keys, webhook URLs).
You can use multiple adapters at once --- Fredy will send new listings through all of them.

Job 📅

A job combines providers and adapters.
Example: "Search apartments on ImmoScout24 + Immowelt and send results to Slack + Telegram."
Jobs run automatically at the interval you configure (see /conf/config.json).

MCP Server 🤖

Starting 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. The local LLM can even enrich existing listings by checking the listing online.

For more information on how to set it up and use it, please refer to the MCP Readme.

💶 Financing Calculator

Finding a place you like is one thing. Working out whether you can actually pay for it is another. The Financing page answers the question the listing page cannot: what would this cost me every month, and does it fit?

Every job now says whether it searches for something to rent or something to buy, and the finance page has one tab for each. Both sit on the same household block - income for one or two people, living costs, any loan you are already paying off - and both are judged by the same rule of thumb: housing costs plus existing debt at or below 35 % of net income.

Renting

Portals quote the Kaltmiete, but a household pays warm. Set the Nebenkosten surcharge once and Fredy reports the highest cold rent you can take on, what that comes to warm, and what is left over each month. Nothing else is asked for: someone who only ever rents is never made to answer a question about Grunderwerbsteuer.

Buying

The buying tab models the purchase the way a German bank would, as an Annuitätendarlehen:

the monthly rate, and how it splits into interest and repayment over the years
the Kaufnebenkosten: Grunderwerbsteuer for your Bundesland, Notar + Grundbuch, and the Maklerprovision. On a 400.000 € house in NRW these add roughly 46.000 € that has to be financed or covered from your own pocket
the Restschuld left when the Zinsbindung runs out, which is the amount you have to refinance at whatever rates exist then
the age at which you and your partner become debt-free
the highest purchase price that keeps you inside the 35 % rule

Several loan scenarios can be compared side by side. Each carries a Sollzins, a Tilgung, a Zinsbindung, a monthly rate and an optional Sondertilgung. Tilgung and monthly rate are the same number seen from opposite ends, so editing either one rewrites the other and you can work from whichever figure you actually have. The term is calculated at a constant Sollzins; what a follow-up loan costs after the Zinsbindung is anyone's guess, so the Restschuld is reported instead of a made-up rate.

It follows you around the app

Each half saves and deletes on its own, and once a half is saved it shows up elsewhere:

an affordability filter on the listings overview, next to the status and provider filters, plus a small verdict chip on each listing
a rent card or a financing card on the listing detail page, whichever matches the job that found the listing

Which yardstick a listing gets follows the deal type of its job, so a 1.200 € rent is never mistaken for an absurdly cheap house. Everything stays hidden until the matching half exists, so nothing changes for anyone who does not use this.

An LLM can ask the same question over MCP with the calculate_financing tool, which returns a mortgage answer or a rent answer depending on the listing.

This is an estimate, not financial advice. The Grunderwerbsteuer rates ship as editable defaults and Bundesländer change them from time to time, so check the figure for your state and get a binding offer from your bank before committing to anything.

Immoscout

Immoscout 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

🛡️ Bot Detection & Proxies

Most browser-based providers (immowelt, immonet, kleinanzeigen, ...) are scraped through a hardened headless browser (CloakBrowser). It makes the browser fingerprint indistinguishable from a real Chrome, which is enough when you run Fredy on a normal home connection.

On 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.

The fix: a residential proxy

A 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.

Configure it under Settings → Execution → Proxy URL. Supported formats:

http://user:pass@host:port
socks5://user:pass@host:port

Leave 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.

Where to get a residential proxy

Residential proxies are a paid service (usually billed per GB, Fredy's traffic is small). Well-known providers offering German residential IPs include:

Provider	Notes
IPRoyal	Pay-as-you-go, no monthly minimum, good for low volume
Webshare	Cheap entry tier, has a small free plan to test with
Decodo (formerly Smartproxy)	Easy setup, country/city targeting
SOAX	Residential + mobile, fine-grained geo-targeting
Bright Data	Largest pool, most features, higher complexity/price
Oxylabs	Enterprise-grade, larger plans

This 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).

Analytics

Fredy 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. Before you freak out, let me explain...
If you agree, Fredy will send a ping once every 6 hours to my internal tracking project (Will be open sourced soon).
The 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.

Thanks🤘

🐞 Debug Information

Since Fredy 22.5.0 there is a built-in way to capture everything Fredy logs into the database for a limited time and download it as a single zip file. This is the recommended way to attach diagnostics to a bug report. I decided against simply putting all logs into a debug bundle due to privacy reasons!

How it works

Debug logging is opt-in and admin-only. As long as it is off, Fredy behaves exactly as before (console output only, nothing in the DB).
When you turn it on, every log line (debug, info, warn, error) is additionally written into the debug_logs SQLite table. The console keeps logging at its usual level.
The recorded data is hard-capped at 5 MiB via a rolling buffer: once the cap is hit, the oldest entries are dropped automatically so the newest ones always survive.
The on/off flag is persisted, so debug logging stays on across restarts (and you'll see the warning banner everywhere until you turn it off again).

Capturing a debug bundle

Open Fredy as an admin and go to Settings → Debug.
Click "Enable debug logging" / "Debug-Logging aktivieren". A red banner appears on every page while recording is on.
Reproduce the bug.
Come back to Settings → Debug and check the progress bar, if it stayed at 0 %, nothing was captured.
Click "Download debug information" / "Debug Informationen herunterladen". You get a zip named YYYY-MM-DD-FredyDebug-<version>.zip containing two files:
- logs.txt - every log line captured while recording was on, prefixed with timestamp and level.
- sys.txt - runtime snapshot (Fredy version, Node.js version, OS, Docker detection, CPU, memory, sanitized settings). Proxy credentials and session secrets are stripped before export.
Attach the zip to the bug report.
Optional but recommended: click "Disable debug logging" to stop recording, and "Delete stored debug logs" once you've sent the zip so the DB does not keep them around.

What is not included

passwords/privacy relevant things
Anything that Fredy itself does not pass through its logger. If a third-party library writes directly to process.stderr, that output stays on the console only.

🛠️ Development

Development Mode

yarn run start:backend:dev
yarn run start:frontend:dev

You should now be able to access Fredy from your browser. Check your Terminal to see what port the frontend is running on.

Run Tests

"Online" tests

These tests are directly executed against the actual providers.

yarn run test

"Offline" tests

These tests are using the test fixtures instead of the actual providers. Much faster and "good enough" to test the core functionality.

yarn run test:offline

Download new fixtures

If you have to refresh the fixtures (every once in a while needed because the providers change their code), run this command:

yarn run download-fixtures

Adding a new language

Fredy'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.

Example: ui/src/locales/fr.json

{
  "_meta": {
    "flag": "🇫🇷",
    "name": "Français",
    "locale": "fr-FR",
    "semiLocale": "fr"
  },
  "nav.dashboard": "Tableau de bord",
  "common.save": "Enregistrer",
  ...
}

The _meta fields:

Field	Description
`flag`	Unicode flag emoji shown in the language selector
`name`	Display name shown in the language selector
`locale`	BCP 47 locale string used for date and number formatting (e.g. `fr-FR`)
`semiLocale`	Semi UI locale key for component-level strings (date pickers, pagination, etc.)

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 for the full list of supported keys.

After 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.

📐 Architecture

flowchart TD
 subgraph Jobs["Jobs"]
        A1["Job 1"]
        A2["Job 2"]
        A3["Job 3"]
  end
 subgraph Providers["Providers"]
        C1["Provider 1"]
        C2["Provider 2"]
        C3["Provider 3"]
  end
 subgraph NotificationAdapters["Notification Adapters"]
        F1["Adapter 1"]
        F2["Adapter 2"]
  end

    A1 --> B["FredyPipelineExecutioner"]
    A2 --> B
    A3 --> B
    B --> C1 & C2 & C3
    C1 --> D["Similarity Check"]
    C2 --> D
    C3 --> D
    D --> E{"Duplicate?"}
    E -- No --> F1
    F1 --> F2

🤖 Using AI such as Claude Code

When I started building Fredy, LLMs were still basically the wet dream of a few nerdy scientists.

Nowadays, 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.

That 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.

So, if you want to contribute to Fredy, using AI tools to get things done is totally fine. Just please don’t stop thinking.

I’ve had one too many PRs full of hallucinated bullshit.

Thanks ;)

👐 Contributing

Thanks to everyone who has contributed!

See the Contributing Guide.

fredy