Installation

Mezite ships as a set of self-contained binaries, published with signatures you can verify before you install. With the default SQLite backend, there are zero external dependencies. Choose the method that fits your environment — Homebrew for a client-only install, or the release archives anywhere else.

Releases are published at github.com/leonardaustin/mezite/releases, with a signature over every release you can check before installing.

Prerequisites

• SQLite (default, zero dependencies) or PostgreSQL 16 (recommended for production)
• Linux or macOS host (amd64 or arm64)

What each release publishes

Every release publishes four archives — Linux and macOS, amd64 and arm64 — and each archive contains all four binaries: mezhub, mezd, msh and mezctl, plus LICENSE and README.md. Alongside them are the files you need to verify what you downloaded.

Download URLs

Every asset is available at two stable URLs. The latest form always resolves to the newest release:

https://github.com/leonardaustin/mezite/releases/latest/download/mezite-linux-amd64.tar.gz

and the version-pinned form always resolves to exactly one release. Archive names carry no version, so pin by tag rather than by filename. Use the pinned form for anything automated — CI, configuration management, container builds — so a new release cannot change what your pipeline installs:

https://github.com/leonardaustin/mezite/releases/download/v0.2.24/mezite-linux-amd64.tar.gz

Homebrew (client only)

The msh client is published as a Homebrew cask, for macOS and for Linux hosts running Homebrew:

brew install leonardaustin/tap/msh

msh version

This installs msh only. It deliberately does not put mezhub, mezd or mezctl on your PATH — a laptop that needs to connect to a cluster should not end up carrying a server binary. To run a server or an agent, use the release archives below.

macOS Gatekeeper. The macOS binaries are ad-hoc signed, not notarized with Apple. Homebrew clears the quarantine attribute for you, so a brew install runs without a prompt. A binary you download from the release page in a browser will be quarantined, and macOS will refuse to run it until you clear the attribute — see Install below for the command.

APT (Debian and Ubuntu)

A mezite APT package is not published yet. There is no repository to add and nothing to apt install today. On Debian and Ubuntu, install from the release archives below — this section will carry the repository and install steps once packages are actually being published.

Release archives

The archives work everywhere: any Linux distribution, macOS, air-gapped hosts, and container images you build yourself. Download, verify, then install.

1. Download

Set PLATFORM to one of linux-amd64, linux-arm64, darwin-amd64 or darwin-arm64, then fetch the archive along with the checksum manifest and its signature:

PLATFORM=linux-amd64
BASE=https://github.com/leonardaustin/mezite/releases/latest/download

curl -fsSL "$BASE/mezite-$PLATFORM.tar.gz" -o "mezite-$PLATFORM.tar.gz"
curl -fsSL "$BASE/checksums.txt"           -o checksums.txt
curl -fsSL "$BASE/checksums.txt.bundle"    -o checksums.txt.bundle

2. Verify

The signature covers checksums.txt, not each archive individually. So verification is two steps: check that checksums.txt is genuinely ours, then check that your archive matches the entry in it. Skipping the second step verifies a signature over a file you never used.

Signing is keyless, through Sigstore: there is no long-lived Mezite signing key to distribute or rotate. Instead, the certificate in the bundle attests that the signature was produced by our release workflow, and that is what the two flags below assert. The identity names our build repository, which is where the release workflow runs; the release itself is published to leonardaustin/mezite.

# 1. Is checksums.txt signed by the Mezite release workflow?
cosign verify-blob \
  --bundle checksums.txt.bundle \
  --certificate-identity-regexp '^https://github\.com/leonardaustin/mezite-mono/\.github/workflows/release\.yaml@refs/tags/v' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  checksums.txt

# 2. Does the archive you downloaded match the manifest you just verified?
#    --ignore-missing skips the platforms you did not download.
sha256sum --ignore-missing -c checksums.txt

On macOS, sha256sum is not present; use shasum -a 256 --ignore-missing -c checksums.txt instead. Install cosign with brew install cosign, or from the cosign releases.

Both commands must succeed. cosign prints Verified OK, and the checksum step prints mezite-<platform>.tar.gz: OK. Check the exit status if you are scripting this. If either step fails, stop: do not extract the archive.

3. Install

The archive is flat — it has no top-level directory, and alongside the four binaries it carries LICENSE and README.md. Do not untar it straight into /usr/local/bin, or those two files land on your PATH as well. Unpack into a scratch directory and install only the binaries you want:

TMP=$(mktemp -d)
tar -xzf "mezite-$PLATFORM.tar.gz" -C "$TMP" mezhub mezd msh mezctl

sudo install -m 0755 "$TMP/mezhub" "$TMP/mezd" "$TMP/msh" "$TMP/mezctl" /usr/local/bin/
rm -rf "$TMP"

mezhub version

On macOS the binaries are ad-hoc signed but not notarized with Apple, so anything downloaded through a browser arrives with a quarantine attribute and Gatekeeper will refuse to run it. Clear it after installing:

for bin in mezhub mezd msh mezctl; do
  sudo xattr -d com.apple.quarantine "/usr/local/bin/$bin" 2>/dev/null || true
done

Installing only the client, or only the agent, works the same way — every archive carries all four binaries, so name just the one you need. On a laptop that only has to reach a cluster, install msh alone and leave the server binaries out:

TMP=$(mktemp -d)

# Just the client, on a workstation
tar -xzf "mezite-$PLATFORM.tar.gz" -C "$TMP" msh
sudo install -m 0755 "$TMP/msh" /usr/local/bin/

# Or just the agent, on a node you are adding to the cluster
tar -xzf "mezite-$PLATFORM.tar.gz" -C "$TMP" mezd
sudo install -m 0755 "$TMP/mezd" /usr/local/bin/

rm -rf "$TMP"

Verifying releases from automation

manifest.json is the machine-readable form of the same information: the release version, an RFC 3339 timestamp, and the size and SHA256 of every archive. Automation that needs to answer "which version is current, and what should this file hash to?" can read one document instead of parsing checksums.txt.

{
  "version": "0.2.24",
  "released_at": "2026-07-30T13:56:54Z",
  "files": [
    {
      "name": "mezite-linux-amd64.tar.gz",
      "os": "linux",
      "arch": "amd64",
      "size": 43819083,
      "sha256": "e7a157574aa25a98a8d4c8b30c8396c244afec9da50d21ef7bd6f59bf3d093bf"
    }
  ]
}

It is signed with a plain ed25519 key rather than through Sigstore, so verifying it needs no special tooling. manifest.json.sig is a base64-encoded detached signature over the exact bytes of manifest.json, and release-signing.pub is the matching public key in PEM form, republished with every release:

BASE=https://github.com/leonardaustin/mezite/releases/latest/download
curl -fsSL "$BASE/manifest.json"        -o manifest.json
curl -fsSL "$BASE/manifest.json.sig"    -o manifest.json.sig
curl -fsSL "$BASE/release-signing.pub"  -o release-signing.pub

base64 -d < manifest.json.sig > manifest.json.sig.raw
openssl pkeyutl -verify -pubin -inkey release-signing.pub \
  -rawin -in manifest.json -sigfile manifest.json.sig.raw
# Signature Verified Successfully

Verify the signature before trusting any hash in the file, and pin release-signing.pub out of band if you want the check to mean something in a compromised-download scenario — a public key fetched from the same place as the file it verifies proves only that the two agree.

Because the manifest is signed over its exact bytes, do not reformat or re-serialise it before verifying — round-tripping it through a JSON tool that reorders keys or changes whitespace will invalidate the signature.

Verify Installation

Confirm the binaries are on your PATH and report the version you expect. Every binary supports the same version subcommand, and --format=json makes it easy to assert on in a script:

mezhub version
mezd version
msh version
mezctl version

# Machine-readable: version, git commit and build date
msh version --format=json

Each binary also prints its usage and full subcommand list with --help. If the commands are not found, make sure /usr/local/bin (or wherever you placed the binaries) is on your PATH.

Container Images

There is no public container registry for Mezite today. The hosted service runs from a private registry that is not available for self-hosted installs, and no first-party public image is published.

To run Mezite in a container or on Kubernetes, build your own image on top of the release archive above — mezhub is a statically-linked binary with no runtime dependencies beyond a CA bundle, so a minimal base image and the verified archive are enough. Podman / Docker Deployment has a working Containerfile and Compose example. The ports each service listens on are in the Configuration reference.

Other package managers

YUM/DNF and RPM-based feeds are not published. On RPM distributions, install from the release archives above; the pinned archive URL is the supported path for configuration management and CI.

Windows

Native Windows builds of the msh client and the agent are not available. Windows users with WSL2 can install the Linux msh binary inside the WSL distribution and use it from VS Code, the Windows Terminal, and any WSL-aware tool.

Next Steps

• Quickstart — Set up a working SSH cluster in five minutes.
• Configuration — Full reference for mezite.yaml.
• Architecture — Understand how the components fit together.