---
title: "Install HitKeep with Homebrew on macOS and Linux | HitKeep"
description: "Install, verify, upgrade, and back up HitKeep on macOS ARM64 or Ubuntu Linux AMD64 and ARM64 with the official Homebrew tap."
canonical: "https://hitkeep.com/guides/installation/homebrew/"
---

# 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](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](https://hitkeep.com/reference/configuration/) 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](https://github.com/PascaleBeier/hitkeep/releases/latest), 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](https://hitkeep.com/guides/data/backups-and-restore/) for restore procedures and [S3 Backups](https://hitkeep.com/guides/data/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](https://hitkeep.com/guides/installation/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](https://hitkeep.com/guides/installation/binary/) for systemd-based servers.

[Previous Installation overview](https://hitkeep.com/guides/installation/)[Next Binary installation](https://hitkeep.com/guides/installation/binary/)