Gas City

“Composable orchestration infrastructure for multi-agent coding workflows.” An open-source Go platform for building your own multi-agent system: you declare a city of AI coding agents in TOML, and an orchestrator keeps reality matching that declaration — starting and stopping sessions, routing work, running scheduled automation — while every unit of work lives as a durable, queryable record called a bead. Write a formula and that orchestrator runs it as a graph across your whole fleet: decomposing the job into beads, fanning ready ones out to many agents, gating each step on its dependencies, retrying failures, and driving it to completion outside your session.

All facts verified against the linked sources on 2026-08-09, at the v1.4.0 tag (released 2026-07-24) — every source link on this page is pinned to v1.4.0, so quotes stay checkable. The project moves fast — trust the live docs over this page for anything newer.

v1.4.1 released 2026-08-15, after this page's verification pass — not yet re-checked against it.

The idea: orchestration as infrastructure

Every serious multi-agent setup ends up rebuilding the same machinery: something to start and supervise agent processes, something to track work that outlives any one session, something to let agents message each other, something to run jobs on a schedule and restart what breaks. Gas City extracts exactly that machinery from Gas Town — Steve Yegge's 20-to-30-agent “coding factory” — into a primitive-first platform. Six primitives (agent, bead, formula, rig, pack, event) are generic; every behavior, including all of Gas Town's famous roles, is just configuration layered on top. The engdocs state the design goal plainly: “The same SDK can express Gas Town, Ralph, or any other pack” — “the orchestrator hardcodes zero roles — no built-in ‘manager’ or ‘reviewer.’” [README · how-gas-city-works · nine-concepts]

Concretely, the README's feature list is the whole story in five bullets: declarative city configuration via city.toml; work routing with Beads-backed tracking, formulas, molecules, waits and mail; runtime providers “tmux, subprocess, exec, ACP, Kubernetes, and herdr”; a controller/supervisor loop that reconciles desired state to running state; and packs, overrides, and rig-scoped orchestration for multi-project setups. [README]

Where it came from

Gas Town launched in January 2026 as Yegge's opinionated “industrialized coding factory manned by superintelligent robot chimps”: seven fixed worker roles, merge queues, patrol loops, operational complexity he compared to Kubernetes. Gas City v1.0 — built by Julian Knutsen and Chris Sells, announced April 2026 — deconstructs that application into composable packs. Two ideas from the announcement shape everything: full observability with git-versioned audit trails (Dolt) turning “dark factories” into light factories, and pool-first reliability — “any agent can go temporarily insane, at any time, and make a bad call.” The human's role shifts to “shepherds, tending flocks of agents which do the ground-level work.” [Welcome to Gas Town · Welcome to Gas City]

Vital statistics

What changed in v1.4.0

If you learned Gas City on the 1.3 line, five things moved. Each gets its full treatment in the section named beside it.

Sources: repo · README · Yegge announcement · Gas Town origin post

2 · The mental model

Three sentences carry the whole system. You declare what should exist — agents, projects, methods, schedules — in city.toml and the packs it imports. An orchestrator daemon makes reality match, reconciling running sessions against that declaration on every tick and driving formula runs forward. All state lives in beads — “everything is a bead: tasks, mail, molecules, convoys, and epics” — so work survives any crash, and agents pull work instead of being pushed to. [glossary · life-of-a-bead]

Since v1.4.0 the docs name a canonical model: six primitives, each answering one question, sitting on three pieces of role-agnostic machinery — the orchestrator (runs formulas, reconciles sessions), the bead store (durable work), and the event bus (fires activity outward). “None of this machinery knows what your agents do.” [how-gas-city-works]

Sources: how-gas-city-works · nine-concepts · engdocs glossary · dashboard

3 · Install & first city

Labs in this guide were written against gascity v1.4.0 docs (fetched 2026-08-09) on macOS with Homebrew. Homebrew installs all runtime dependencies for you (tmux, jq, dolt, bd…); the manual dependency table only matters for direct-download or source builds. Building from source needs Go 1.26+ (pinned in go.mod as 1.26.4). [installation]

brew install gascity
gc version

gc init ~/bright-lights
cd ~/bright-lights
gc status
gc dashboard

The dashboard, rebuilt around runs

v1.4.0 changed what gc dashboard is. The UI is “a single-page app compiled into the gc binary and served by the supervisor on its own listener, so there is nothing extra to install or run” — the old standalone static server (and its --port flag) is gone. gc dashboard now resolves the supervisor URL, opens your browser, and prints the URL; --no-open prints without launching (handy over SSH). If the supervisor isn't running it tells you how to start it instead of opening a dead URL. One supervisor serves every registered city — pick yours from the header switcher. [dashboard · CLI]

The headline feature is run detail: the release notes describe it as unifying “the formula stage ladder, structured transcripts, live token rate, and estimated burn rate,” with session and run reads moved onto “typed, paginated API surfaces backed by warm projections instead of ad hoc wire shapes.” A late fix (PR #4436) restored tokens/min and burn/hr for long-lived pool sessions by sweeping model usage at each interval end — so those fields populate even when agents self-drive after their initial claim. [v1.4.0 release notes]

Command-usage metrics (new in v1.4.0)

Official release builds of gc now record privacy-scoped command-usage metrics. The disclosure is shown before the first eligible interactive command is recorded, and that first invocation is never recorded — collection begins with the next one. Unversioned, development, test, and CI builds fail closed and cannot collect. Events carry “only a canonical command ID, the gc release, operating system, and an anonymous installation ID — never arguments, paths, file contents, or environment values.” [release notes · CLI]

gc metrics status          # redacted local state
gc metrics example         # the exact request shape that would be sent
gc metrics off             # durable opt-out: disables, purges queued data, removes the ID
gc metrics on              # accept the disclosure (verified TTY)

# environment-level opt-outs, per process
export DO_NOT_TRACK=1
export GC_DISABLE_USAGE_METRICS=1

Note the asymmetry: DO_NOT_TRACK=0 or GC_DISABLE_USAGE_METRICS=0 “never forces collection on and never overrides a saved opt-out. There is no environment force-enable.” Don't confuse this with [usage] and gc costs (§4) — those are your own local cost accounting and go nowhere off the machine.

brew update && brew upgrade gascity
cd ~/bright-lights
gc doctor --fix            # run this once per existing city, before anything else
gc start

Sources: installation · quickstart · dashboard · troubleshooting · v1.4.0 release notes

4 · city.toml anatomy

Everything section 2 called “desired state” is written here. Only [workspace] is required; a useful minimal city is four blocks. Below, the documented minimal example with the fields you'll touch first, annotated. [config reference]

# ── required: city-level metadata ─────────────────────────────
[workspace]
name = "my-city"

# ── how to launch an agent CLI (a named preset) ───────────────
[providers.claude]
command = "claude"
args = ["chat", "--no-interactive", "--agent", "gascity"]

# ── a configured worker; behavior comes from its prompt ───────
[[agent]]
name = "polecat"
provider = "claude"
# scope = "rig"                 # where it may load: "city" | "rig"
# min_active_sessions = 1      # pool floor…
# max_active_sessions = 3      # …and ceiling
# wake_mode = "resume"         # or "fresh" per wake
# drain_timeout = "5m"         # default grace on shutdown

# ── an external project this city orchestrates ────────────────
[[rigs]]
name = "myrig"
path = "/path/to/rig"
# prefix = "mr"                # bead-ID namespace for this rig

The rest of the schema, by neighborhood

Templates: fields like work_dir, session_setup, on_boot, and work_query accept placeholders — {{.Session}}, {{.Agent}}, {{.Rig}}, {{.RigRoot}}, {{.CityRoot}}, {{.WorkDir}} and friends — resolved per session. [config reference]

New command surface in v1.4.0

Nothing was removed from the CLI in this release; these command families are additions. Most of them read or write config you now know where to find.

Sources: config reference (city.toml schema) · CLI reference · connected clients

5 · Work routing: beads, formulas, molecules, waits & mail

Gas City is a pull system. Nothing pushes a task into an agent's prompt; work is written into the bead store, and each agent's hook query finds what's addressed to it. The docs put the contract in capitals: “If you find work on your hook, YOU RUN IT” — the run-what-you-find rule. [life-of-a-bead]

The primitives, one by one

Sling is the everyday verb: gc sling <target> "<task>" creates a bead and routes it — to a fixed agent by setting its assignee, to a pool by labeling it pool:<name>, and with --formula it cooks and routes in one motion. Pool agents then claim with bd update <id> --claim. [quickstart · life-of-a-bead]

Formulas go through three stages: TOML file → in-memory recipe (flattened steps plus dependency edges) → materialized beads, independent of the file. “Work persists, so whoever picks it up next finds the same state.” Preview with gc formula show, materialize without routing via gc formula cook, detect drift with gc formula version-check. [understanding-formulas]

formula = "feature-flow"
[vars]
feature = "the feature"

[[steps]]
id = "design"
title = "Design {{feature}}"

[[steps]]
id = "implement"
needs = ["design"]        # readiness gate: runs when design closes

Molecules and wisps. A molecule is “a formula instantiated at runtime: one root bead plus zero or more provider-managed step beads.” A wisp is “an ephemeral bead produced by a v1 formula run” — created by gc sling or order dispatch, auto-closed and garbage-collected once both wisp_gc_interval and wisp_ttl are set (wisp GC is disabled unless both are). The core pack's cleanup order tidies all three outcomes above: it reaps stale ephemeral runs and purges closed step records, with cleanup edges covering v2 workflows too. [glossary]

Convoys group related beads into a tracked batch (“a container bead that groups related issues”), with blocking needs edges between members; when all children close, the convoy auto-closes. Orders automate dispatch: a trigger — cooldown, cron, condition, event, or manual — paired with a formula (gc order list, gc order run). [glossary · life-of-a-bead · CLI]

Mail is messaging built from beads: a message is a bead with Type="message", sender in From, recipient as assignee; your inbox is “the set of open, unread message beads assigned to a recipient.” Reading adds a read label but keeps the bead open; archiving closes it. Threads are labels (thread:<id>). Nudges are the opposite trade-off: text sent straight into a session to wake or redirect it — fire-and-forget, no persistence, lost if the session isn't running. Waits are durable session waits — a session blocks on a condition and survives it (gc wait inspects them). [messaging · session · CLI]

Two compiler contracts — and why v2 is the one to learn

This is the decision v1.4.0's docs put first, ahead of every pattern. “Both contracts are live and supported. They are peers, not a version ladder — each makes a different thing the engine.” Under v1 the engine is the agent you sling to; under v2 it is the orchestrator. [understanding-formulas]

“For new work, choose v2. The opt-in is one table”:

[requires]
formula_compiler = ">=2.0.0"

Base constructs (steps, needs, children, condition, loop, vars, extends) mean the same in both. Graph-only constructs — check, retry, drain, on_complete, tally, and reserved gc.* step metadata — require the declaration; compiling without it fails telling you exactly which table to add. The host-side [daemon] formula_v2 switch defaults to on, and the deprecated contract = "graph.v2" key still parses with a gc doctor warning.

Two v1-only edges remain, “neither a reason to start on v1”: gc converge accepts only v1 formulas (use a v2 check loop for iterate-until-it-passes instead), and container dependencies have a v2 gap — the v2 compiler creates no parent-child edges yet, so a needs on a parent gates only on that parent step; list the children explicitly until #3451 lands.

Verb vs outcome: cook, sling, or order

Three verbs create formula instances, and the outcome follows from the contract rather than from a separate choice. Cook (gc formula cook <name>) creates without routing — nothing wakes up; use it to inspect beads first, route yourself, or graft a sub-DAG onto existing work with --attach <bead-id>. Sling (gc sling <target> <name> --formula) cooks and routes in one motion. Orders are scheduled dispatch: a trigger plus a formula (or a shell command — never both), instantiated and routed to the order's pool each time it fires. [understanding-formulas]

# a toy project to orchestrate
mkdir ~/hello-world && cd ~/hello-world && git init && cd -

# register it with the city, then sling work at an agent
gc rig add ~/hello-world
cd ~/hello-world
gc sling claude "Create a script that prints hello world"

# watch the bead move open → in_progress → closed
bd show <bead-id> --watch

# and see the same activity as events
gc events

Sources: understanding-formulas · life-of-a-bead · messaging · glossary · CLI reference

6 · Runtime providers

Agents don't care where they run. The [session] block picks a backend city-wide (or GC_SESSION for one process); every backend implements the same provider contract, so the orchestrator's logic — and your config — stays identical from a laptop tmux pane to a Kubernetes pod. One rule to remember: “tmux is the default session backend and the fallback, so it stays required even if you run agents on another backend.” v1.4.0 pushed this further: provider routing, ACP/automatic runtime selection, Herdr-backed sessions, and Kubernetes/subprocess/tmux execution now “share one session lifecycle and worker boundary,” with pool demand, wake, resume, drain, close, and orphan recovery all reasoning from persisted session/work identity rather than provider-specific shortcuts. [config reference · README]

# 1 · per-process trial on a throwaway city — nothing committed
GC_SESSION=herdr gc start <scratch-city>

# 2 · promote to that scratch city's default, run it end to end
[session]
provider = "herdr"

# 3 · widen to the real city only after several stable work cycles

Sources: config reference · herdr-provider · session architecture · README

7 · Multi-project: rigs, packs & overrides

One city, many codebases, shared behavior — this is where Gas City earns the “composable” in its tagline. Three mechanisms do the work: rigs isolate projects, packs share configuration, and overrides/patches specialize it per place.

Rigs: project isolation

Registering a repo (gc rig add) gives it its own bead scope, hook installation, and routing context; the rig's prefix namespaces its bead IDs so queries never leak across projects. Under the hood “the city and all its rigs share one underlying store, and reads and writes are filtered to the current scope's prefix” — the isolation is the prefix, not a separate database, but it is enforced hard enough that cross-scope routing is refused (§5). Rig config can set its own formulas_dir, formula_vars, session caps, and default sling targets — default_sling_targets (plural, new in 1.4) takes a list and picks one at random per targetless dispatch, taking precedence over the singular form. [how-gas-city-works · config reference]

Packs: shared behavior via named imports

“A pack is a directory with a pack.toml file” — agents in agents/, formulas in formulas/, plus prompts, orders, commands, skills. Imports are named bindings, and the binding qualifies every imported agent name: import a pack as gascity and you address its planner as gascity.planner, never bare planner. Imports live at city level, or under a [[rigs]] entry — which stamps the rig's identity onto the imported agents. [understanding-packs]

Keep two identifiers apart, because only one is portable. A registry handle like main:gascity finds a pack on this machine — main is your local registry name and another machine could call it work. A durable source like https://github.com/gastownhall/gascity-packs/tree/main/gascity is what you commit, “independent of any machine's registry name or cache.” Use the handle to search (gc pack registry …); write the source into your TOML. New in 1.4: gc import credential manages credentials for private pack sources. [understanding-packs · CLI]

The layering order (memorize the last line)

city.toml + city pack
  → imported packs (+ pack-level patches)
  → city-level imports → city-level patches
  → rig-level imports (stamp rig agents) → rig overrides
  → pack globals
  → city agent defaults

“Later layers win for replacement-style fields. Defaults run last but only fill blanks, so they never override an explicit value from an earlier layer.” Session-cap precedence runs agent > rig > workspace; an agent's scope field (city, rig, or omitted for both) says where a definition may load — “it does not name a particular rig.” [understanding-packs · config reference]

mkdir ~/second-project && cd ~/second-project && git init && cd -
gc rig add ~/second-project

gc rig                 # both rigs listed
gc config explain      # every resolved value, with which layer set it

Sources: understanding-packs · config reference · quickstart

8 · The reconcile loop

Kubernetes users will feel at home: the orchestrator is a declarative convergence engine. Desired state comes from city.toml parsed with includes and patches; observed state comes from Provider.ListRunning() plus session metadata; reconcileSessionBeads() continuously repairs the divergence. The whole cycle lives in controllerLoop() and runs every patrol_interval (default 30s). [controller]

Failure handling

• Graceful termination is two-pass: “(1) send Interrupt (Ctrl-C) to all sessions, (2) wait shutdown_timeout, (3) force-kill survivors via Stop().”
• Crash loops hit a breaker: the crash tracker quarantines agents using a sliding window — “max_restarts within restart_window” — so a broken agent can't consume resources forever.
• Health patrol is just an order: “probe sessions… compare thresholds… publish stalls… restart with backoff” — remediation composed from the same primitives as any other automation.
• Pool capacity is fenced (new in 1.4): claim ownership, wake budgets, slot selection, and confirmed-dead cleanup are “fenced against stale or partial observations,” so pool sessions no longer lose or strand work while draining, restarting, or reusing capacity.
• Degraded is now said out loud: managed beads and Dolt paths — provider health, endpoint ownership, lock release, compaction, reindexing, stale data-dir cleanup, partial store reads — “preserve errors instead of silently reporting complete state.”

[controller · nine-concepts]

Above the loop: the supervisor

The machine-wide supervisor exposes the “typed HTTP + SSE control plane” (OpenAPI-documented) that the dashboard and gc events consume — and since v1.4.0 it serves the dashboard SPA itself, same-origin, out of the gc binary. Its API defaults to loopback with mutation controls and auth keys in [api]; the event log is file-backed JSONL with rotation (gc events rotate). v1.4.0 bounded these paths under load: “the CLI drains paginated event windows, request paths avoid unbounded scans, tmux sessions keep their shared server, and structured transcripts preserve tool and error frames.” [reference index · config reference · CLI]

Sources: engdocs controller · nine-concepts · reference index

9 · Code tour

The repo splits cleanly: cmd/gc/ holds the CLI and the controller; internal/ holds 106 top-level packages (150 Go package directories at v1.4.0, up from 76/105 at v1.3.0) implementing the primitives; docs/ is the user manual and engdocs/ the contributor manual. Start reading with three engdocs files: nine-concepts.md (the layering), life-of-a-bead.md (the data flow), controller.md (the loop). [internal/ · engdocs/architecture]

Details worth knowing before you patch anything

• Provider contract: lifecycle (Start/Stop/Interrupt), observation (IsRunning, ListRunning, Peek, GetLastActivity…), interaction (Attach/Nudge/SendKeys), metadata, and staging (CopyTo/RunLive). Optional extensions: InteractionProvider, IdleWaitProvider, ImmediateNudgeProvider. Rules: Stop is idempotent; ProcessAlive returns true on empty process lists.
• Session identity: agent.SessionNameFor() is “the single source of truth for runtime session naming”; beacons (startup ID strings) let restarted sessions be recognized and adopted after crashes.
• Store implementations: BdStore (Dolt-backed, production), FileStore, MemStore, and an exec store — all behind the same CRUD + parent-child + dependencies + labels + query contract.
• The invariant that bites: “Only non-nil fields in UpdateOpts are applied. Labels append, never replace.”
• Where v1.4.0's new surface lives: 30 top-level packages appeared under internal/. The ones that map to features in this guide are usage and productmetrics (usage facts and command-usage metrics), eventfeed and transcriptmeta (paginated feeds, structured transcripts), poolplan, warmup and orderdispatch (pool sizing and dispatch), clientauth/clientgrant/citywriteauth/clientcontext (remote cities and signed grants), webhookmatch/webhooksink/webhookverify, and rig, storeref, doltorphan for store scoping and repair. engdocs/architecture/ lost tally-control.md (21 docs → 20).

[session · nine-concepts · life-of-a-bead]

Sources: internal/ tree · engdocs/architecture tree · session.md · controller.md

10 · Gas Town → Gas City

The migration doc's core instruction: don't import Gas Town's surface area — “re-express the intent in Gas City's primitives.” The deepest change is ownership: the orchestrator now “owns reconciling desired→running sessions, session scaling, order evaluation, health patrol” — duties Gas Town distributed across role agents. Roles didn't die; they became configuration, and ship today as the Gastown pack (mayor, polecat, witness, refinery, deacon, boot). v1.4.0's rewrite of that page adds the second half of the story: “the orchestrator can now run a formula as a graph across many agents, out of your session — decomposing a job into beads, fanning the ready ones out in parallel, gating each step on its dependencies, and retrying failures to completion. Your single-agent, in-session formulas still run (v1); this fleet orchestration (v2) is what's new.” Because it is a platform, a feature added to Gas City lifts every orchestrator built on it — Gas Town included. [coming-from-gastown · command map]

Roles & concepts

Muscle-memory table (most-typed commands)

Dropped without direct equivalent — usually on purpose: gt broadcast, gt notify, gt dnd, gt escalate, gt whoami, gt checkpoint, gt patrol, gt seance, gt mq (merge queue), gt callbacks, gt issue. Hardcoded role types, path-derived config, and helper agents for shell work are explicitly gone. [command map · coming-from-gastown]

Sources: coming-from-gastown · gastown-command-map

11 · Quiz, glossary & sources

Twenty-two questions, weighted toward the mental model and work routing, with the last four on what v1.4.0 changed. Reveal, then score yourself honestly — 17+ is mastery.

Glossary

Sources

Everything above traces to these. All sources fetched 2026-08-09 and pinned to the v1.4.0 tag, so every quote on this page stays checkable even as main moves on.

Official — user docs

• github.com/gastownhall/gascity — repo · README · v1.4.0 release notes
• Getting started: how-gas-city-works (the six primitives) · installation · quickstart · dashboard · troubleshooting · FAQ · coming-from-gastown
• Guides: understanding-formulas · understanding-packs · configuring-an-agent · harness-recipes · connected-clients
• Reference: config (city.toml schema) · cli · gastown-command-map · herdr-provider · formula-spec-v2 · reference index
• Runbooks: remote-hardened-city

Official — contributor architecture (engdocs)

• nine-concepts (retitled “Code-layering View (implements the six primitives)”) · controller · dispatch · life-of-a-bead · glossary · messaging · session

Lineage

• Yegge — “Welcome to Gas Town” (Jan 2026) · Yegge — “Welcome to Gas City” (Apr 2026)