Documentation Index
Fetch the complete documentation index at: https://docs.gascityhall.com/llms.txt
Use this file to discover all available pages before exploring further.
Which method should I use?
| Method | Best for | Installs deps? | Auto-upgrades? |
|---|
| Homebrew | macOS / Linux daily use | Yes (all 6) | brew upgrade |
| Direct download | CI, containers, air-gapped hosts | No | Manual |
| Source build | Contributors, bleeding-edge | No | Manual |
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 | 1.86.2 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 |
| Go 1.25+ | Source only | 1.25 | brew install go | golang.org | Compiler |
| make | Source only | — | (built-in) | apt install make (or build-essential) | Drives make install |
ccf7bde206, which can hang dolt_backup sync
under heavy write load.
The exact versions CI pins are in deps.env.
Homebrew (recommended)
brew install gastownhall/gascity/gascity
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:
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
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.1.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
gastownhall/gascity repository:
gh attestation verify "${ARCHIVE}" --repo gastownhall/gascity
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 separately when
using direct download. Homebrew handles this automatically. Build from source
Requires make and Go 1.25+ (pinned in go.mod).
git clone https://github.com/gastownhall/gascity.git
cd gascity
make install # builds and installs to $(GOPATH)/bin/gc
gc version
make build # outputs bin/gc in the repo root
./bin/gc version
make build automatically ad-hoc code-signs the binary (codesign -s -).
Contributor setup
After building, install the dev toolchain and pre-commit hooks:
make setup
make check # runs fmt, lint, vet, and unit tests
Verify your installation
Regardless of install method, confirm everything is working:
gc version # should print the installed version and commit
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 and starts it automatically.
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:
Or run a link check without starting the server:
