Install Geometer

Requirements#

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, no Intel Mac build and no Linux desktop app 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:

The Mac app#

1. Download Geometer-0.1.0-alpha.2-macos-arm64.dmg from the latest release.
2. Open the disk image and drag Geometer to Applications.
3. Open Geometer. The alpha is not signed by Apple yet, so macOS refuses to open it the first time.
4. Open System Settings, then Privacy & Security. Scroll to the message about Geometer, click Open Anyway and confirm.
5. Open Geometer again. It signs you in to its own local workspace and shows the welcome page.
6. Optional: press Add the geo command on the welcome page (or on This computer) if you also want geo in a terminal, in your coding assistant or in npx @geometer/init. The app carries the geo command inside it, at Geometer.app/Contents/Resources/bin/geo, the same version as the app.

The card shows exactly what it will do before it does anything: make one link, ~/.local/bin/geo, to that copy, the same place the terminal installer uses. It never asks for a password, never uses sudo and never edits a shell file. If something is already at ~/.local/bin/geo that is not this app's, it leaves it alone and says so. If ~/.local/bin is not on your PATH, the card shows the one line to add (with a copy button) and which file it belongs in; you add it yourself. Afterwards it says Done. `geo` now works in a new terminal. Install the app in Applications first: from the disk image the link would break when you eject it, and the card says so.

The link is a link, not a copy. If you move or delete the app, run Add the geo command again from the new place. Even with no link, npx @geometer/init and geo mcp install find the copy in /Applications or ~/Applications, and the app's Wrap your MCP servers card uses it directly.

If you prefer the terminal, you can remove the quarantine mark instead of using System Settings:

xattr -dr com.apple.quarantine /Applications/Geometer.app

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 and geo-guard 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"

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.
• There is no desktop app. Run geo open in a terminal. It starts the workspace on 127.0.0.1 only, prints a one-time sign-in link and, when run from a terminal, opens your browser. Add --no-browser to only print the link.
• 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. On the welcome page and on a project page, a Docker card says in plain words whether Docker is ready, stopped or missing, and 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.

The card shows the exact commands first and runs nothing until you press its button. 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 card updates by itself.

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 a link to the Docker card and one plain sentence to pass on. Press the card's button, 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.

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. To upgrade the Mac app, download the new disk image and install it the same way as the first; the new version backs up your records before it first opens them, and macOS asks you to allow it once more. 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. For the Mac app, also drag Geometer from Applications to the Bin.

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. The Mac app, the geo command and the workspace in your browser all read the same folder.

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

Next#

• QuickstartOpen a project and run your first check.
• TroubleshootingDocker not running, the unsigned app, a sign-in link that does not work.