Skip to content

installation.md

Latest commit

 

History

History
259 lines (193 loc) · 8.49 KB

installation.md

File metadata and controls

259 lines (193 loc) · 8.49 KB
Raw
title Installation
description Install Gas City from Homebrew, a release tarball, or source.

Which method should I use?

Method Best for Installs deps? Auto-upgrades?
Homebrew macOS / Linux daily use Yes (runtime deps) brew upgrade
Direct download CI, containers, air-gapped hosts No Manual
Source build Contributors, bleeding-edge No Manual

Most users should use Homebrew. It installs all runtime dependencies automatically and keeps gc on your PATH. Choose direct download when you cannot use Homebrew (CI images, Docker layers, machines without package managers). Choose source when you need unreleased changes or plan to contribute.

Prerequisites

Gas City requires a small set of runtime tools. Homebrew installs all of them for you; the other methods require manual installation.

Tool Required Min version macOS Linux Notes
tmux Yes — brew install tmux apt install tmux Session management
jq Yes — brew install jq apt install jq JSON processing
git Yes — (built-in) (built-in) Version control
dolt Yes 2.1.0 or newer brew install dolt releases Beads data plane
bd (Beads CLI) Yes 1.0.0 brew install beads releases Issue tracking
flock Yes — brew install flock (built-in via util-linux) File locking
gh Optional — brew install gh cli.github.com GitHub gate checks
Go 1.26+ Source only 1.26 brew install go golang.org Compiler
make Source only — (built-in) apt install make (or build-essential) Drives make install

Use a final Dolt 2.1.0 or newer. Gas City's managed Dolt checks reject older and pre-release builds because they are below the managed bd/Dolt compatibility floor; releases before 1.86.2 can also miss the upstream GC/writer deadlock fix in dolthub/dolt commit ccf7bde206, which can hang dolt_backup sync under heavy write load.

The exact versions CI pins are in deps.env.

Homebrew (recommended)

brew install gascity

This taps the gastownhall/gascity formula, downloads the matching gc release asset, and installs all six runtime dependencies (tmux, jq, git, dolt, flock, beads).

Once Gas City is accepted into homebrew-core, the normal install path will be brew install gascity; the gastownhall/gascity tap remains available for emergency updates.

Verify the installation:

gc version
If you use Oh My Zsh with the `git` plugin, `gc` may already be an alias for `git commit --verbose`. Run `command gc version` once to bypass the alias. For a persistent fix, add `unalias gc 2>/dev/null` or `zstyle ':omz:plugins:git' aliases no 'gc'` after Oh My Zsh loads in `~/.zshrc`, or put that line in a file such as `~/.oh-my-zsh/custom/gascity.zsh`.

Upgrading via Homebrew

brew update
brew upgrade gascity

After upgrading, restart any running city so the supervisor picks up the new binary:

gc service restart     # restarts the launchd/systemd service

gc start auto-regenerates the service file on each invocation, so a brew upgrade followed by gc start always picks up template changes (see v0.13.3 release notes).

Uninstalling via Homebrew

gc stop <city-path>                        # stop running city first
brew uninstall gascity
brew untap gastownhall/gascity             # remove the tap

Direct download

Release tarballs are published for every tagged version. Supported platforms:

OS Architecture Archive name
macOS (darwin) Apple Silicon (arm64) gascity_VERSION_darwin_arm64.tar.gz
macOS (darwin) Intel (amd64) gascity_VERSION_darwin_amd64.tar.gz
Linux x86_64 (amd64) gascity_VERSION_linux_amd64.tar.gz
Linux ARM (arm64) gascity_VERSION_linux_arm64.tar.gz

Download and install

# Set the version you want (check https://github.com/gastownhall/gascity/releases)
VERSION=1.3.0

# Detect platform
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m)
case "$ARCH" in
  x86_64)         ARCH=amd64 ;;
  aarch64|arm64)  ARCH=arm64 ;;
esac

# Download and extract
curl -fsSLO "https://github.com/gastownhall/gascity/releases/download/v${VERSION}/gascity_${VERSION}_${OS}_${ARCH}.tar.gz"
tar -xzf "gascity_${VERSION}_${OS}_${ARCH}.tar.gz"

# Move to a directory on your PATH
sudo install -m 755 gc /usr/local/bin/gc

# Verify
gc version

Verify release artifacts

Homebrew verifies release checksums from the formula automatically. For direct downloads, verify the archive before installing it:

ARCHIVE="gascity_${VERSION}_${OS}_${ARCH}.tar.gz"
CHECKSUMS="gascity_${VERSION}_checksums.txt"

curl -fsSLO "https://github.com/gastownhall/gascity/releases/download/v${VERSION}/${CHECKSUMS}"
grep "  ${ARCHIVE}$" "${CHECKSUMS}" > "${ARCHIVE}.sha256"

if command -v sha256sum >/dev/null 2>&1; then
  sha256sum -c "${ARCHIVE}.sha256"
else
  shasum -a 256 -c "${ARCHIVE}.sha256"
fi

Release archives are also published with GitHub artifact attestations. If you have the GitHub CLI installed, verify the downloaded archive against the gastownhall/gascity repository:

gh attestation verify "${ARCHIVE}" --repo gastownhall/gascity

Each release also includes an SPDX SBOM asset:

curl -fsSLO "https://github.com/gastownhall/gascity/releases/download/v${VERSION}/gascity-v${VERSION}.spdx.json"

Upgrading a direct-download install

Repeat the download steps above with the new version number. The gc binary is a single static file — overwriting it is safe.

You still need to install the [prerequisites](#prerequisites) separately when using direct download. Homebrew handles this automatically.

Build from source

Requires make and Go 1.26+ (pinned in go.mod as 1.26.4).

git clone https://github.com/gastownhall/gascity.git
cd gascity
make install        # builds and installs to $(GOPATH)/bin/gc
gc version

To build without installing globally:

make build          # outputs bin/gc in the repo root
./bin/gc version

On macOS, make build signs the binary with a stable local codesigning identity when one is available, which helps macOS remember local permission grants across rebuilds. Without a stable identity, the build leaves Go's linker-produced signature unchanged. Set GC_SIGN_IDENTITY=<certificate name> to choose a specific certificate, GC_SIGN_IDENTIFIER=<identifier> to use a separate local TCC identity, or GC_ADHOC_SIGN=1 to opt into ad-hoc signing for a local experiment. Successful local signing also removes stale com.apple.provenance metadata when present.

Contributor setup

After building, install the dev toolchain and pre-commit hooks:

make setup
make check          # runs fmt, lint, vet, and unit tests

See CONTRIBUTING.md for the full contributor workflow.

Verify your installation

Regardless of install method, confirm everything is working:

gc version          # should print the installed version and commit

If that runs git commit instead of Gas City, your shell has a gc alias. Use command gc version for this check and see Troubleshooting for the permanent fix.

Then create your first city:

gc init ~/my-city
cd ~/my-city

gc init registers the city with the supervisor, which then starts it. By the time the command returns, the city is running. See the Quickstart for a complete walkthrough.

Gas City ships a JSONL archive that snapshots every bead database for disaster recovery. By default it runs in local-only mode and keeps commits on this host. To enable off-box backup, see JSONL archive push failures.

Docs preview

The docs site uses Mintlify. Preview locally from the repo root:

./mint.sh dev

Or run a link check without starting the server:

make check-docs