Installation

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.4 minimum; 1.3.1 tested	`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. The tested bd is v1.3.1: brew install beads (or brew upgrade beads) installs it, or download bd for your platform from the v1.3.1 release assets. With bd v1.3.0 Gas City falls back from its native store to the bd CLI, and proxied bd backup and closed-wisp purge are skipped. Gas City 1.4.2 pairs the native store with Beads 1.3.0, and main pairs it with Beads 1.3.1, which keeps the same schema. When upgrading an existing shared database from Beads 1.2.2, coordinate the upgrade of all clients using that database, then run bd migrate schema from the workspace (for a city, see Migrate the Beads schema). The tested upgrade moves schema 53 to 66 and preserves existing beads. Older clients cannot use the migrated schema. Fresh workspaces initialize directly at the new schema. To install the exact release archive pinned by CI:

set -a && . ./deps.env && set +a && .github/scripts/install-bd-archive.sh "$BD_VERSION"

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

The gascity formula depends on beads, so this upgrades bd too. After upgrading, run gc start for each city. When the supervisor is still running the old binary, gc start restarts it on the new one, and it regenerates the supervisor’s service file on each invocation, so a brew upgrade followed by gc start always picks up template changes. An upgrade that changes the Beads version can also need a backup and a one-time database migration. Before upgrading a city you rely on, follow Upgrading an existing city.

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.4.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. Install the matching bd as well, and see Upgrading an existing city for the backup and Beads migration steps.

You still need to install the 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

make install and make build produce the binary you run. To change Gas City itself, you test with Bazel: CI checks every pull request with bazel test, and the make targets below run the same commands. Install Bazelisk, which reads the Bazel version the repo pins, then set up the dev toolchain and git hooks:

make setup
echo 'build --config=fork-cache' >> .bazelrc.local   # read CI's build cache
make check          # bazel test //...: unit tests, lint, vet, formatting, generated files

The fork-cache line points Bazel at the project’s anonymous, read-only cache, so anything CI already built or tested is reused instead of rerun on your machine. Nothing you build is uploaded.

Change	Run
Any change	`make check`
`gc` command behavior	`make test-acceptance`
Runtime, orchestrator, or formula behavior	`make test-integration`
Docs	`make check-docs`
Added packages, files, or imports	`make bazel-sync`, then commit the result

Plain go test ./... still works for a quick check of one package, but it is not what CI runs and skips the lint, formatting, and generated-file checks. See CONTRIBUTING.md for the full contributor workflow and the Bazel quickstart for remote execution and troubleshooting.

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

Getting Started

Tutorials

Guides

Troubleshooting

Reference

Which method should I use?

Prerequisites

Homebrew (recommended)

Upgrading via Homebrew

Uninstalling via Homebrew

Direct download

Download and install

Verify release artifacts

Upgrading a direct-download install

Build from source

Contributor setup

Verify your installation

Docs preview

​Which method should I use?

​Prerequisites

​Homebrew (recommended)

​Upgrading via Homebrew

​Uninstalling via Homebrew

​Direct download

​Download and install

​Verify release artifacts

​Upgrading a direct-download install

​Build from source

​Contributor setup

​Verify your installation

​Docs preview

Which method should I use?

Prerequisites

Homebrew (recommended)

Upgrading via Homebrew

Uninstalling via Homebrew

Direct download

Download and install

Verify release artifacts

Upgrading a direct-download install

Build from source

Contributor setup

Verify your installation

Docs preview