Install Geometer

Geometer is a download, not a service. Install the geo command, make sure Docker is running, and you are ready to check your first project.

Requirements

What Geometer needs on macOS and on Linux

Need	macOS	Linux
Processor	Apple silicon (M1 or later). Intel Macs are not supported in the alpha.	x86_64 or arm64
System	Tested on macOS 26. Built for macOS 12 and later, which has not been tested.	Any recent distribution. The binaries are static.
Containers	Docker Desktop or Colima, Docker version 24 or newer.	Docker Engine usable by your user, with the compose and buildx plugins.
Disk	About 2 GB free for container images and records.	The same.
What you get	The geo command, with geo-guard, geo-verify and geo-model-gateway beside it.	The same.

On Linux, docker compose version and docker buildx version should both answer. Without the compose plugin Geometer cannot find your project’s services, and without buildx it cannot build images in the usual way.

The first check downloads the container images your project needs, usually a few hundred megabytes, and installs your project’s dependencies inside the containers. That needs a network connection once. Later checks reuse what was downloaded. A free local model, if you choose one, is a separate download of about 5 GB. See Choose a model.

There is no Windows build and no Intel Mac build in the alpha.

What you can download

Every release is published on the GitHub releases page and listed with its digests on the download page. The alpha has these files:

Files in release 0.1.0-alpha.2

File	For
geo-0.1.0-alpha.2-macos-arm64.tar.gz	The terminal on a Mac (Apple silicon)
geo-0.1.0-alpha.2-linux-x86_64.tar.gz	The terminal on Linux x86_64
geo-0.1.0-alpha.2-linux-aarch64.tar.gz	The terminal on Linux arm64
SHA256SUMS and release.json	The SHA-256 digest of every file, and the list of files
ghcr.io/geometerlabs/geo:0.1.0-alpha.2	The Docker image that runs geo ci on Linux CI

Install in the terminal, on macOS or Linux

Run the one-line installer:

curl -fsSL https://geometer.dev/install.sh | sh

In order, the installer:

1. Looks at your computer. It accepts macOS on Apple silicon and Linux on x86_64 or arm64, and it stops with a plain message on an Intel Mac or any other system, having installed nothing.
2. Downloads the matching geo-<version>-<system>-<processor>.tar.gz and SHA256SUMS from the GitHub release.
3. Checks the tarball’s SHA-256 digest against SHA256SUMS, using sha256sum or shasum. If it differs, or the file is not listed, it stops and installs nothing.
4. Unpacks the tarball into a temporary folder and runs the tarball’s own install.sh, which installs for you alone.
5. Opens your Geometer records once by running geo doctor, so any upgrade of the records happens now, with its result shown, instead of in the middle of your first check.

It never uses sudo and refuses to run as an administrator. It changes nothing outside the install folder and your Geometer records folder. By default it installs under ~/.local, puts geo in ~/.local/bin, and adds geo-verify, geo-guard and geo-model-gateway next to it. If that folder is not on your PATH, it prints one command to paste. If Docker is not ready, it ends by printing geo doctor --fix or, in a terminal, offering it.

Check that it worked:

~/.local/bin/geo --version

Then see a first result on a practice agent. If Docker is not ready, this is where Geometer offers to set it up:

~/.local/bin/geo practice --check

To read the script before running it, download it first:

curl -fsSL https://geometer.dev/install.sh -o install.sh
less install.sh
sh install.sh

Installer options

Options go after sh -s -- when you pipe the installer:

curl -fsSL https://geometer.dev/install.sh | sh -s -- --prefix "$HOME/tools"

Installer options and settings

Option or setting	What it does
--prefix DIR	Install under DIR instead of ~/.local. System folders such as /usr and /Applications are refused.
--home DIR	Use DIR for your Geometer records instead of ~/.geometer-host.
--rollback	Go back to the previous version. See Upgrade, roll back, uninstall.
GEO_VERSION	An environment variable that installs another release than the one the script names, for example GEO_VERSION=0.1.0-alpha.2.
--help	Shows a short description and does nothing.

Install by hand from a tarball

If you do not want to pipe a script into your shell, download the tarball for your system and SHA256SUMS from the release, check the digest, unpack it and run its installer.

# macOS
shasum -a 256 -c SHA256SUMS --ignore-missing
# Linux
sha256sum -c SHA256SUMS --ignore-missing

tar -xzf geo-0.1.0-alpha.2-linux-x86_64.tar.gz
cd geo-0.1.0-alpha.2-linux-x86_64
./install.sh

The tarball’s install.sh takes the same --prefix, --home and --rollback options. It copies the program beside the old one and then switches, so a failed copy leaves the working version as it was. It also checks the adapter bundle that ships inside the tarball and stops if it does not match.

Linux notes

• The binaries are static, so they run on both glibc and musl systems.
• Install Docker Engine yourself. Geometer installs nothing for Docker on Linux. It shows instructions when Docker is missing. Your user must be able to talk to Docker without sudo.
• geo guard login-item, which starts Guard at login on a Mac, is not available on Linux. Use geo guard start --supervise or your own service manager instead.

The Docker image for CI

On Linux CI systems you can run the checks without installing anything. The image runs geo and uses the host’s Docker for its containers. It starts no Docker of its own.

docker run --rm --network host \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$PWD:$PWD" -w "$PWD" \
  ghcr.io/geometerlabs/geo:0.1.0-alpha.2 ci

Run kept checks in CI explains each part and the exit codes.

Docker and Colima

Geometer runs your project, its database and the simulated services in containers, so it needs Docker running. On a Mac, either Docker Desktop or Colima works. geo doctor says in plain words whether Docker is ready, stopped or missing, and geo doctor --fix offers one action: start Docker Desktop, start Colima, or, on a Mac with Homebrew and no Docker at all, install Colima and the Docker command line and then start Colima.

It shows the exact commands first and runs nothing until you say yes. It never uses sudo. If you would rather set Docker up yourself, install Docker Desktop or Colima as you normally would and come back.

The same offer is made wherever Docker is needed:

• In a terminal. When geo check, geo practice --check, geo ci or another command that runs containers finds Docker missing or stopped, it shows the same commands, asks Run them now? [y/N], runs them if you say yes, and then carries on with your command. Say no and nothing runs. geo doctor --fix does the same without running a check.
• At the end of the installer. If Docker is not ready, the installer prints one command, geo doctor --fix. When you run the installer from a terminal rather than a pipe, it starts that setup for you, and it still shows the commands and asks first.
• In your coding assistant. When you ask it to check your agent and Docker is missing or stopped, it gets one plain sentence to pass on: run geo doctor --fix (or, where Geometer cannot set Docker up, the steps to install it), then ask again.
• In scripts and CI. Nothing is ever asked. You get the message with the one thing to do, and the exit code is 3 (an infrastructure failure), as before.

If Homebrew is missing, or on Linux, Geometer shows instructions instead, because it never runs commands that need administrator rights.

Tested only in part

The terminal offer and the installer have been tested on a Mac that has Docker, with stand-ins for Homebrew, Colima and Docker: the commands shown, the question, no running anything on “no”, and running the commands and continuing on “yes”. The real brew install colima docker, and starting a real Docker Desktop or Colima that was stopped, have not yet been tested on a Mac that lacked them. If an offer does not work, start Docker yourself and check again. Messages for a missing, stopped and too old Docker have been tested.

To see what Geometer thinks of your set-up from a terminal, run geo doctor. It reports Docker, disk space, your records and leftovers, and repairs what it can. Add --fix to also set Docker up when it is missing or stopped.

Upgrade, roll back, uninstall

Upgrade. Run the installer again, either the one-line installer or the newer tarball’s install.sh. The previous version stays installed, and Geometer copies your records to a backup before the new version opens them. There is no update check and no automatic update.

Roll back. Run the installer again with --rollback. It returns to the previous version and, if the upgrade changed the format of your records, puts back the copy made before it. The newer records are set aside, not deleted. If the upgrade did not change the records’ format, only the program goes back and the installer says so.

# from the unpacked newer release
./install.sh --rollback
# or with the one-line installer
curl -fsSL https://geometer.dev/install.sh | sh -s -- --rollback

Uninstall. The installed program carries its own uninstaller:

~/.local/lib/geometer/current/uninstall.sh

It first runs geo gc to remove the containers, networks and images that Geometer created, stops any Guard program that was started from this install (with Geometer gone, nothing could manage it) and then removes the program and the links in bin. Your records stay unless you add --purge-records. It takes --prefix DIR and --home DIR if you installed somewhere else.

Where your records live

Geometer keeps its records, such as checks, problems, kept-check history, Guard files and exports, in one folder: ~/.geometer-host. Set the environment variable GEO_HOME to move it, or pass --home DIR to any geo command. Every geo command reads the same folder.

What is inside the records folder

Folder or file	What it holds
backups/	Copies of the records made before an upgrade changes their format
practice/	The practice project, a copy of a sample refund agent
exports/	Exported evidence and certificates. Geometer writes exports here, never into your project
guard/	Guard’s files for each project
network-ledger.jsonl	The host and port of each network call Geometer itself made, such as a model download

Geometer writes into your project only when you keep a check. See Privacy and security.

Next

• Quickstart (Run your first check.)
• Troubleshooting (Docker not running, geo not found, a check that cannot start.)