This site is self-hosted on HomeFree — running everything you see, on the same box.

Update Checks

Once a day, your HomeFree box asks the HomeFree project's update server whether a newer version is out. That is the only contact the box makes on its own by default, so this page lists exactly what it sends and what happens to it. The switches are on the Privacy page in the admin UI (under System), at the top.

Why the project counts the checks

HomeFree is very new, and we have no idea how many people are using it. Every change to HomeFree has to work on every box already out there, so before we can drop an old setting, remove a migration, or stop supporting an old version, we need to know whether boxes still run it. Counting the daily checks tells us how many boxes run each version. That is the whole purpose.

What a check sends

{
  "v": 1,
  "rev": "944a3ec2c1f0...",
  "ref": "main",
  "count": true
}
Field What it is
v The version of this message format.
rev The HomeFree commit your box runs (a public commit in the HomeFree repo).
ref The branch your box follows for updates.
count true on the box's first check of the day, false on any later one, so a box is counted at most once a day.

There is no ID, no name, no domain, and nothing else about the box. The update server answers with the newest commit on your branch and how many commits you are behind, which the Updates page shows. The Privacy page shows the exact message your box sends, built from its real values.

What the update server keeps

Daily totals only: on each day, how many boxes reported each version (and, if they opted in, each usage detail below). It keeps no IP addresses: its web address writes no access log, and the server never reads the address of whoever is calling. Because a check carries no ID, the server cannot tell two checks from the same box apart, or follow a box from one day to the next.

The totals are published at https://updates.homefree.host/api/v1/stats. Any value fewer than three boxes reported is folded into "other", so a rare setup cannot be singled out.

Usage details (opt-in)

Off unless you turn on Include usage details. When on, the first check of each day also carries:

Detail Example
Built-in apps that are turned on forgejo, immich (apps from add-on plugins are never listed)
Router or server mode router
Processor architecture x86_64-linux
NixOS release 26.05
Boot mode, and whether Secure Boot is on uefi, false
System disk layout single or raid1
Whether the system disk is encrypted true
Backup destinations in use local, backblaze
How long ago the box was installed week, month, half-year, or older
Memory size 16-32 (GB, as a range)

These tell the project which apps and setups to test against, and which ones a change would affect. They are counted the same way as the version, one tally per value, so the server never holds a box's combination of details.

If a future version of HomeFree adds anything to this list, your box stops sending details until you turn the switch on again.

Local copies and forks

A box that builds from a local copy of the HomeFree code (a git checkout of the official repository) checks like any other box, but rev is the newest commit of its branch that the copy is built on, taken from the copy's own record of the official repository. That commit is already public, so the check never carries your own commits, your branch names, or anything about changes you have not committed, and it looks the same as a check from a box running that commit. Its Updates page shows that commit with the copy's location, and updating means pulling the branch into the copy, then pressing Apply.

Boxes that build from another HomeFree repository online, such as a fork, never send a check.

Turning checks off

Switch off Check for updates automatically and press Apply. The box then makes no update check on its own at all. The Updates page still checks when you open it, by asking the HomeFree code repository for its newest commit, which sends nothing about your box.

When an update has been waiting

If an update has been available for a week, the HomeFree update alert fires (and, if you set up phone notifications, tells you). It clears once you pull the update in on the Updates page (or, for a local copy, into the copy). You can turn the alert off on the Alerts page.