3. Installation

freemapper is a single program without an installer.

1. On the release page, download the archive for your system:

   • Windows: freemapper-…-windows-x86_64.zip
   • Mac with Apple chip (M1 and newer): freemapper-…-macos-arm64.tar.gz
   • Mac with Intel processor: freemapper-…-macos-x86_64.tar.gz
   • Linux: freemapper-…-linux-x86_64.tar.gz

   The .gz files and freemapper-update.json on that page are for freemapper update; you do not need them.

2. Unpack the archive with a double click. Put the folder in a fixed place, e.g. Documents/freemapper.

3. On the first start the system warns you, because the program is not signed:

   • Windows: "Windows protected your PC" → More info → Run anyway.
   • macOS: "cannot be opened …" → System Settings › Privacy & Security → Open Anyway.

Note the full path to the program, e.g. C:\Users\Anna\Documents\freemapper\freemapper.exe or /Users/anna/Documents/freemapper/freemapper. The assistant needs it.

Besides the program, the folder holds the READMEs, the licence, this manual and AGENTS.md, instructions for AI assistants (chapter 4).

Updating

freemapper update puts the newest release in place of the program. The path stays the same, so an assistant that knows freemapper by its path keeps working with it. Versions 0.11.0 and older cannot update themselves. For them, download the newest archive once as in step 1 and replace the program in your folder with the one from the archive. From then on the command does it.

./freemapper update

The command shows the new version, its release date, the link to the release notes and the download size, and asks Install it now? [y/N]. Only y or yes installs (in German also j and ja). These switches change what it does:

Checks before the swap. Each release carries a list of its program files with their sizes and SHA-256 checksums, signed with the project's minisign key. freemapper has the public half of that key built in. It installs only when the signature and the checksums match, otherwise it reports the error and the old program stays. Then it starts the new program once with --version. Only if that prints the expected version does the new program take the place of the old one.

The previous version. The replaced program stays next to the new one as freemapper.previous (Windows: freemapper.previous.exe). --rollback swaps the two back, and a second --rollback returns to the newer one.

Program folder. freemapper must be able to write to the folder it lives in. It does not ask for administrator rights. If the folder is write-protected, the message names it; unpack the new release there by hand, or move freemapper to a folder you can write to. If you start freemapper through a link such as ~/.local/bin/freemapper, the update replaces the file the link points to.

Built from source. A freemapper you built yourself with cargo does not update itself. freemapper update then only says to update it with git pull and cargo build --release --locked, and there is no daily check.

The daily check

After find, init, select, fetch, run and permits, which go online anyway, freemapper checks at most once a day whether a newer release exists. derive and export work offline and do not check. The check runs while the command works. If it finds a newer version, one line follows the command's own output on the error output (stderr):

freemapper 0.12.0 is available (you have 0.11.0). Update with: freemapper update

The line can also come after an error message; even in mode install freemapper then installs nothing. The check has 3 seconds from the start of the command, so a very fast command can take up to 3 s longer. freemapper drops a check that takes longer. A dropped or failed check shows nothing and still counts for the day, so a computer without internet asks once a day and not with every command. The time and result of the last check are in update-check.json in the cache folder.

There is no daily check with --offline, when the environment variable CI is set (as on build servers), in mode off, or in a build from source.

Modes

freemapper update --mode install stores the mode in the file settings.toml:

• Windows: %APPDATA%\freemapper\settings.toml, e.g. C:\Users\Anna\AppData\Roaming\freemapper\settings.toml
• macOS: ~/Library/Application Support/freemapper/settings.toml
• Linux: ~/.config/freemapper/settings.toml, or $XDG_CONFIG_HOME/freemapper/settings.toml if that variable is set

The file then holds mode = "install" under [update]. The environment variable FREEMAPPER_UPDATE with off, notify or install overrides the file while it is set; --mode tells you when it does. FREEMAPPER_CONFIG_DIR names another folder for the file. --mode also works in a build from source, because it only writes the file.

To switch the check off for good, run freemapper update --mode off. For one terminal session, set FREEMAPPER_UPDATE=off.

What freemapper sends

The check asks github.com for two small files of the newest release: the update manifest freemapper-update.json and its signature. GitHub forwards the request to its download servers, and freemapper follows it only to release-assets.githubusercontent.com and objects.githubusercontent.com. An install then loads the program file for your system from there. Each request carries only the fixed User-Agent freemapper/<version> (+https://github.com/HenryJobst/freemapper), the same as for the geodata. freemapper sends no ID, no project data and nothing about you.

With an assistant

The MCP server checks once a day too, and it never installs on its own. When it knows a newer version, its next answer to the assistant ends with a note for you. The assistant should then ask you, and only once you agree does it call the tool install_update. The tool check_update only checks. A running MCP server keeps the old version until the assistant restarts it; in Claude Desktop, quit the app and open it again. AGENTS.md gives the assistant these rules.

The area page in the browser shows a line with the command when the last daily check found a newer version. The page itself installs nothing.