Gas City: an orchestration-builder SDK for multi-agent coding workflows

The problem Gas City extracts from Gas Town

Gas City is not a coding agent. It is the infrastructure that sits around several of them. The README describes it as an "orchestration-builder SDK for multi-agent systems" that "extracts the reusable infrastructure from Gas Town into a configurable toolkit". That sentence is the whole pitch and also the boundary: if you already run one agent in one terminal, Gas City adds nothing you need. It becomes relevant when you have more than one agent, more than one repository, and a desire to describe the desired state of that arrangement in a file instead of in a shell script.

The audience is Go developers building internal agent tooling, not end users looking for a chat interface. The repository layout confirms this. cmd/gc/ holds CLI entrypoints and controller wiring, internal/runtime/ holds the provider abstraction, internal/config/ holds the city.toml schema, and pkg/ exists alongside internal/, which is the usual signal that some code is meant to be imported. The README also points experienced Gas Town users at a migration document, docs/getting-started/coming-from-gastown.md, which maps Town roles, commands, plugins, convoys and directory habits onto Gas City's "primitive-first model". That phrase is a warning: the project deliberately does not reproduce Gas Town's architecture one to one.

How the controller reconciles a city to running state

The mechanism the README names is a "controller/supervisor loop that reconciles desired state to running state". You write a city.toml; the controller reads it and makes the running world match. Everything else in the feature list hangs off that loop.

Work is tracked through beads, which the README describes as backing "work tracking, formulas, molecules, waits, and mail". Sessions run on a runtime provider. The provider list is broad and worth reading carefully: tmux, subprocess, exec, ACP, Kubernetes and herdr. The README states that tmux is both the default backend and the fallback, so it stays required even when agents run somewhere else. That is a design decision with a cost. A Kubernetes-only deployment still carries a tmux dependency, because the fallback path assumes it.

Above the single-city case sit packs, overrides and "rig-scoped orchestration for multi-project setups". A rig appears to be the unit that binds an agent session to a working directory; the quickstart adds one with gc rig add . from inside a git repository. The repository also ships examples/ directories named bd, gastown, hyperscale, lifecycle, storage, swarm and t3bridge-gastown, which is where a reader should look for a configuration that resembles their own before writing one from scratch. The README does not describe the reconciliation interval, conflict resolution between packs and overrides, or what happens when a provider disappears mid-loop.

Installing Gas City and running a first rig

The README gives two install paths. Homebrew is the short one, and it also prints the version so you can confirm the binary is on your PATH.

brew install gascity
gc version

Building from source needs make, Go 1.26.4 or newer, and ICU for a transitive Dolt CGO dependency. On macOS that is brew install icu4c, on Linux apt install libicu-dev, and the Makefile auto-detects the keg-only icu4c paths on macOS.

make install

Gas City checks its prerequisites itself. The README states that gc init and gc start report any missing tools, and the table lists tmux, git, jq, pgrep and lsof as always required. The bd provider additionally needs dolt 2.1.0 or newer, bd 1.0.0, and flock. If you want to avoid that stack entirely, the README gives an escape hatch: set GC_BEADS=file, or add [beads] provider = "file" to city.toml, for a file-based store with no dolt, bd or flock.

The quickstart then initialises a city, starts it, adds a rig and dispatches work. Note that the session attach command targets a role named mayor, which is one of Gas Town's role names carried over.

gc init ~/bright-lights
cd ~/bright-lights
gc start

mkdir hello-world
cd hello-world
git init
gc rig add .

bd create "Create a script that prints hello world"
gc session attach mayor

What you should see is a city directory containing your configuration, a running controller, and a session you can attach to. The README does not document rollback for gc init or gc rig add, so treat the city directory as something to create in a scratch location first rather than in an existing project root.

The ICU and Nix build wall

The most concrete limitation in the README is the build itself. Because Dolt pulls in a CGO dependency on ICU, a plain go build can fail on machines where the headers are not on the default search path. The README names the exact error for NixOS and Flox-managed Linux toolchains: fatal error: unicode/uregex.h: No such file or directory. It then gives a workaround that requires you to resolve two store paths by hand.

ICU_DEV=/nix/store/dvhx24q4icrig4q1v1lp7kzi3izd5jmb-icu4c-76.1-dev
ICU_LIB=/nix/store/i4lj3w4yd9x9jbi7a1xhjqsr7bg8jq7p-icu4c-76.1

CGO_ENABLED=1 \
CGO_CPPFLAGS="-I$ICU_DEV/include" \
CGO_LDFLAGS="-L$ICU_LIB/lib" \
SYS_USR_CGO_FALLBACK=0 \
  make build

The README tells you to re-resolve the dev header path with find when the store path changes, and to match the runtime lib to what your installed binary links with ldd $(which gc) | grep icu. That is a real maintenance burden, and it is version skew sensitive: mismatched headers and libraries are an expected failure mode, not an edge case. The README also warns that releases before 1.86.2 can miss an upstream GC/writer deadlock fix in dolthub/dolt commit ccf7bde206, which "can hang dolt_backup sync under heavy write load". If you run the default bd provider at volume, that is the failure to plan for. The file provider sidesteps both the Dolt version floor and the deadlock, at the cost of whatever durability and concurrency the bd store provides.

Gas City versus Gas Town, and where the SDK stops

The obvious alternative is Gas Town, the project Gas City was extracted from, and the README treats the comparison as important enough to have its own document. The difference in approach is architectural. Gas Town presents a fixed set of roles, commands, plugins, convoys and directory conventions. Gas City presents primitives and expects you to compose them, with the migration guide existing precisely because a literal port of a Town setup will not work.

That makes Gas Town the better choice if you want an opinionated system you can adopt as-is, and Gas City the better choice if you intend to build your own orchestration on top. It also means Gas City is the wrong tool for a single developer running one agent against one repository, where the controller loop, the bead store and the provider abstraction are overhead with no payoff. If you only need an agent in a terminal, skip this entirely.

A second boundary is language. The SDK is Go, module github.com/gastownhall/gascity, and the dependency list is Go-heavy: cobra for the CLI, BurntSushi/toml for city.toml, huma for the HTTP API, OpenTelemetry for telemetry, and the Kubernetes client libraries for the K8s provider. Nothing in the repository suggests bindings for other languages. If your team does not write Go, the SDK is not for you, though the gc binary itself is still usable as a CLI.

Maintenance, licensing and what an upgrade costs

The repository is not archived. The most recent push to main was on 2026-06-27, and the v1.4.1 release is dated 2026-08-15, with v1.4.0 on 2026-07-24. There is also an edge release described as "gascity edge (rolling main)", so the project publishes both tagged releases and a rolling channel. The gap between the last push to main and the v1.4.1 tag means tagged releases and main are not in lockstep, which matters if you pin to a tag and read main's documentation.

Gas City is MIT licensed. That is permissive and imposes no copyleft obligation on your own code, but MIT covers Gas City's source only. The dependency list includes k8s.io/client-go, go-sql-driver/mysql, go-jose, and a Dolt chain pulled in through the beads provider, each under its own licence. If you redistribute a binary, those notices are your problem to collect. This is a description of the licence situation, not legal advice.

The upgrade cost is dominated by the external tools rather than the Go module. The README sets a floor of Dolt 2.1.0 or newer for managed checks, calls out the pre-1.86.2 deadlock, and requires bd 1.0.0. Those are separate binaries you upgrade on their own schedule, and the README's compatibility language ("Gas City's managed bd/Dolt compatibility floor") implies the project tracks them deliberately. The Go side is ordinary: go.mod declares go 1.26.6 while the README's build instructions say Go 1.26.4+, so the toolchain you build with should satisfy the stricter of the two.

Editorial conclusion

Adopt Gas City if you are building multi-agent coding workflows in Go and want the controller loop, work tracking and session backends as a library rather than a monolith, and if you can accept tmux, git, jq, pgrep and lsof as hard prerequisites. Do not adopt it if you want a single binary that runs agents without a runtime dependency, or if your team cannot build with CGO and ICU. Before committing, verify three things: that your Go toolchain meets the 1.26.4+ build requirement, that your Dolt is at 2.1.0 or newer if you keep the default bd provider, and that your agents' providers are actually supported by the runtime backend you plan to run.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes