- JavaScript 46.1%
- Nix 25.9%
- Python 23.3%
- Shell 2.6%
- HTML 0.9%
- Other 1.1%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
Ellis Rahhal
4b64358ba0
Two changes that were staged together and share hunks in module.nix and profiles/router.nix, so they land together. homefree.network.dns-enforcement. AdGuard was doing its job perfectly and still blocking nothing: an LG C1 made 2,567 queries to LGs ACR beacon host, every one blocked, Reason=3, IsFiltered=true — while conntrack showed the same client talking to 8.8.8.8 on port 53. The TV ships a hardcoded fallback resolver and reaches for it the moment a lookup is blocked, and the nat prerouting chain was empty, so every blocked domain was one fallback query away from resolving anyway. It is a device class problem rather than an LG one: Roku, Chromecast, Amazon and Google speakers all ship the same fallback. The query log showing lots of successful blocks is consistent with total bypass and cannot distinguish the two, which is why the note says to diagnose with conntrack rather than infer from AdGuard. A podman shutdown inhibitor, with a VM test. On reboot every containers pre-stop hook calls netavark, which tries to START a transient aardvark-dns scope through systemd-run; systemd refuses that once reboot.target has a start job queued, because the transaction is destructive. Cleanup fails, container stops time out and are SIGKILLed, /home will not unmount because it is busy, and the box sits in late shutdown until the watchdog or a human resets it. Both carry an agent note under docs/agent-notes explaining the failure, how to tell it apart from what it looks like, and what it does not cover. |
||
| .claude/skills/forgejo-backlog | ||
| apps | ||
| assets | ||
| checks | ||
| docs | ||
| flake-modules | ||
| hosts/lan-client | ||
| installer | ||
| lib | ||
| modules | ||
| overlays | ||
| profiles | ||
| provisional | ||
| scripts | ||
| services | ||
| template | ||
| tests | ||
| themes | ||
| web-platform | ||
| .gitignore | ||
| AGENTS.md | ||
| CLAUDE.md | ||
| configuration.example.nix | ||
| configuration.nix | ||
| COPYING | ||
| default.nix | ||
| domain.patch | ||
| fix-caddy-dns01.md | ||
| fix-caddy-dns01.patch | ||
| flake.lock | ||
| flake.nix | ||
| lan-client.nix | ||
| LICENSE | ||
| Makefile | ||
| module.nix | ||
| README.md | ||
| result-1 | ||
| setup-cdn.md | ||
| version.nix | ||
HomeFree
A personal server and router in one box — your apps, your identity, your connectivity, on hardware you own.
Status: technical preview. Production users welcome, but expect some sharp edges.
What it is
HomeFree is a declarative NixOS system that sits between your internet modem and the rest of your home network. Most self-hosting projects are app launchers; HomeFree is also your router — firewall, ad-blocking DNS, dynamic DNS, automatic HTTPS, and a private mesh VPN are built in. On top of that it runs a curated suite of apps, every one of them behind a single sign-on, with encrypted backups to local disk, a NAS, or S3. Router, apps, identity, and backups are configured together and declared in one config — rebuild the whole machine, reproducibly, anywhere.
What's included
Infrastructure — Zitadel SSO + oauth2-proxy (one login, every app), Caddy reverse proxy with automatic TLS, Unbound DNS, AdGuard ad-blocking, multi-zone dynamic DNS, headscale mesh VPN, restic backups (local / NAS / S3), nftables abuse-blocking.
Admin — a web-based installer and an admin dashboard at admin.<domain>, a
per-user app dashboard at home.<domain>, backed by a FastAPI service.
Apps — all opt-in, all gated by SSO: Nextcloud, Immich, Jellyfin, Matrix/Synapse,
Vaultwarden, Home Assistant, Forgejo, Frigate, CryptPad, FreshRSS, Trilium, Ollama,
and more — see apps/ for the full catalog.
Install
The supported path is the guided ISO installer — no command line required:
-
Download the HomeFree ISO from homefree.host.
-
Write it to an 8 GB+ USB stick — balenaEtcher works on any OS, or use
ddif you're on Linux/macOS:# replace /dev/sdX with your USB device — this erases it sudo dd if=homefree-latest.iso of=/dev/sdX bs=4M status=progress oflag=sync -
Boot the HomeFree box from the USB stick and follow the on-screen installer (~20 min).
See the manual for the full walkthrough, including how to wire up the hardware and set your modem and Wi-Fi to bridge mode:
Repo layout
| Path | Contents |
|---|---|
apps/ |
Per-app service modules (Nextcloud, Immich, Zitadel, …) |
services/ |
Core infrastructure (Caddy, DNS, SSO, admin web, landing page) |
modules/ |
System modules (abuse-blocking, geoIP, dynamic DNS) |
profiles/ |
Configuration profiles (boot, networking, router, secrets) |
web-platform/ |
Web installer + admin UI (Lit frontend, FastAPI backend) |
scripts/ |
Build and deploy automation |
flake.nix |
Flake inputs and outputs — the build entry point |
module.nix |
The homefree.* NixOS option schema (single source of truth) |
configuration.example.nix |
Annotated example system configuration |
Development
A host is configured through the homefree.* options declared in module.nix,
supplied per-host via homefree-configuration.nix (the installer writes this).
Flake apps:
nix run .#run-vm # boot the configuration in a QEMU VM
nix run .#build-iso-image # build the installer ISO
nix run .#deploy # build locally and deploy to a remote host
nix run .#flash # write an ISO to a USB stick
scripts/build.sh runs a local nixos-rebuild; scripts/deploy.sh builds locally
and activates the closure on a remote host.
Documentation
- Manual · FAQ · Comparison with other projects
- Backup & restore guide
- The landing page and manual sources live in
services/landing-page/.
License
GPLv3 — see LICENSE.