Install HitKeep with Homebrew on macOS and Linux

Homebrew is the shortest supported installation path for HitKeep on Apple Silicon macOS and Ubuntu Linux on AMD64 or ARM64. The official tap installs the current stable hitkeep binary; HitKeep still stores its data locally and uses the same configuration as every other self-hosted deployment.

Platform	Homebrew support
macOS ARM64 (Apple Silicon)	CI-validated
Ubuntu Linux AMD64/x86_64	CI-validated with Linuxbrew
Ubuntu Linux ARM64	CI-validated with Linuxbrew

Release CI installs the stable formula, upgrades it to the release candidate, verifies the installed version, runs brew test, and uninstalls it on every listed platform.

Quick start

Install HitKeep from the official tap:

brew install PascaleBeier/hitkeep/hitkeep
hitkeep --version

Create explicit persistent directories, generate a session secret, and start a local instance:

mkdir -p "$HOME/.local/share/hitkeep"/{data,archive,backups}

export HITKEEP_PUBLIC_URL=http://localhost:8080
export HITKEEP_JWT_SECRET="$(openssl rand -hex 32)"
export HITKEEP_BIND_ADDR=127.0.0.1:7946
export HITKEEP_DB_PATH="$HOME/.local/share/hitkeep/data/hitkeep.db"
export HITKEEP_DATA_PATH="$HOME/.local/share/hitkeep/data"
export HITKEEP_ARCHIVE_PATH="$HOME/.local/share/hitkeep/archive"
export HITKEEP_BACKUP_PATH="$HOME/.local/share/hitkeep/backups"

hitkeep

Open http://localhost:8080 and complete the setup wizard.

Persist the session secret

The command above is a local quick start. Before relying on this instance, store one stable HITKEEP_JWT_SECRET in a permission-restricted environment file or service configuration. Generating a different secret on every start signs users out.

Use the Configuration Reference for production URLs, mail, storage, S3, MCP, and optional AI settings.

Verify

In another terminal, confirm the installed formula, run the tap’s formula test, and check both runtime probes:

brew list --versions hitkeep
brew test PascaleBeier/hitkeep/hitkeep
curl --fail http://localhost:8080/healthz
curl --fail http://localhost:8080/readyz

/healthz confirms the process is alive. /readyz confirms the shared database and every open tenant database are ready to serve traffic.

Upgrade

Review the release notes, then update Homebrew metadata and upgrade the formula:

brew update
brew upgrade hitkeep
brew list --versions hitkeep

Restart the running HitKeep process after the upgrade. Homebrew replaces the executable; it does not move or delete the data paths you configured.

Backup

The quick start enables HitKeep’s checkpointed backup worker at $HOME/.local/share/hitkeep/backups. Keep that directory on durable storage and test a restore before treating it as a production backup.

A complete backup plan includes:

• the configured HITKEEP_DB_PATH;
• the full HITKEEP_DATA_PATH, including tenants/*/hitkeep.db;
• the configured archive and backup paths;
• any external S3 objects when those paths use s3:// URLs.

See Backups and Restore for restore procedures and S3 Backups for off-machine storage.

Production notes

• Put HTTPS in front of HitKeep and set HITKEEP_PUBLIC_URL to the exact browser-visible URL.
• Configure trusted proxies when traffic passes through a reverse proxy or load balancer.
• Run HitKeep under a macOS service manager if it must start automatically; keep secrets out of shell history and service command arguments.
• Use the Linux binary guide for systemd-based servers.