A Gas City factory composes six public primitives: a Pack configures Agents, Formulas, and Orders; a Formula operates over a convoy of Beads; Agents execute ready work in a Rig; and Events expose activity for observation. The local City is the root pack.
The durable work record belongs to Beads. Gas City’s orchestrator controls execution around that record. A graph-workflow run is materialized as root and step beads. The dashboard and API project its local execution view by folding retained bead lifecycle events and adding live or linked detail; they do not replace the work graph or capture a shared organizational Run.
Customer-owned factory configuration
The factory is the agents, workflows, automations, prompts, skills, packs, and related settings the customer owns.
A pack is the portable definition layer. It declares agents, workflow formulas, automations called orders, and the files they need. The local city is a root pack that can import shared packs. Deployment choices belong in city configuration, while machine-specific bindings and runtime material remain local.
This split keeps working method separate from one machine’s paths and processes. The packs guide documents composition and imports. The current field contract is in the configuration reference.
Imported packs supply the factory’s agent roles and formula workflows, allowing the same orchestrator to run very different factory shapes.
Beads is the durable data plane
Beads stores the units of work and the typed relationships between them. Status, assignment, hierarchy, blockers, provenance, comments, and history survive the agent session that created them.
Gas City’s standard path uses the default bd work-store provider, with Dolt as the source of truth behind the Beads work graph. Embedded mode supports a local single writer; server mode supports concurrent access. Gas City also supports a file provider and exec: adapters for testing or custom integrations. Agents and the orchestrator use the bead-store interface to read ready work, claim it, record progress, and close it.
Every city also persists five infrastructure classes: execution graph, sessions, messaging, orders, and nudges. By default those classes share the work ledger. An optional split-storage layout keeps work in its existing provider while routing all five infrastructure classes to one local sqlite-beads binding. The cutover is explicit—gc storage migrate --from-work --fleet-stopped—and startup refuses a half-migrated layout rather than moving data during boot.
Parent-child edges organize a larger job. Blocking dependencies control readiness. bd ready computes the claimable frontier from those edges.
The Beads architecture docs cover storage and synchronization. Why coding agents need a work graph explains the semantic model.
The Gas City orchestrator drives the graph
A workflow definition, technically a formula, describes steps and their dependencies in readable TOML. Gas City compiles and materializes that method as beads. From that point, the work exists independently of the file and the session that launched it.
The orchestrator drives ready steps forward. It routes work to configured agents or pools, holds blocked work, retries expected failures, and reconciles declared agents with live sessions. An order can start a workflow on a schedule, event, condition, or manual trigger.
This is the control plane. It does not need to contain the durable work in its own process memory because Beads carries that state.
Read How Gas City works for the six public primitives and Understanding formulas for graph materialization.
Configured coding agents execute in projects
A configured agent combines five independent choices: the coding-agent harness, model, model-serving upstream, transport, and runtime. Claude Code, Codex, Gemini CLI, and other harnesses can participate through built-in or custom definitions. CLI and ACP are transports. Runtime backends include local tmux or subprocess, Kubernetes, SSH, and exec: adapters.
When active, the agent is a session: a process Gas City can start, stop, prompt, and observe. Sessions are disposable. Their work remains in Beads.
A registered project or repository is technically a rig. It gives work and agents a project scope. Parallel coding sessions normally use isolated worktrees so changes do not collide in one checkout. The code lives in the repository and worktrees; Beads state remains separate from Git branch commits.
The mixed-agent guide explains the provider boundary.
Events and dashboard provide local observation
Gas City emits operational events as activity occurs. The API supports listing events, streaming them, and resuming from a cursor. The local dashboard reads supervisor and project state to show agents, sessions, beads, workflow activity, mail, and health.
Events are observation signals. The Beads graph is the durable work record.
A lowercase local run has a durable bead identity: graph workflows materialize a root bead and child step beads. The dashboard and API project run state by folding retained bead lifecycle events from .gc/events.jsonl, then enrich request-time views with live session and census state plus linked formula or transcript detail. That local projection is not a separately governed organizational Run. The events reference and API reference describe the current interfaces.
The durable memory and audit-trail guide separates Beads work, Gas City local visibility, and the retained commercial record.
The architecture bends at configuration seams
Gas City keeps its extension points at boundaries an operator can inspect.
- Packs replace or compose the agents, formulas, automations, prompts, skills, services, commands, and runtime definitions that make up the factory.
- Providers adapt coding-agent CLIs, bead stores, sessions, and other machinery behind explicit interfaces.
- City and project configuration select deployment, scope, paths, commands, models, transports, and runtime choices without changing the orchestrator.
- Formula inputs and imports let one workflow method reuse planning, implementation, review, repair, and publication behavior while exposing project-specific choices.
This is how the public Registry can carry complete build methods, focused review disciplines, service adapters, and runtime extensions without folding every variation into the Gas City binary. The factory-in-practice guide shows those seams in the gascity pack the team runs on its public repository fleet.
Where each kind of state lives
| Kind | Owner | Typical location or interface | Durability |
|---|---|---|---|
| Factory definition | Customer pack and city config | pack.toml, city.toml, pack directories | Versionable customer files |
| Work and dependencies | Beads | Work ledger; Dolt through the default bd provider | Durable outside sessions |
| Execution graph, sessions, messaging, orders, and nudges | Gas City coordination classes | Work ledger by default; optional local sqlite-beads binding for all five classes | Persisted locally; lifecycle retention varies by class |
| Source and artifacts | Customer project | Repository, worktree, artifact location | Controlled by project workflow |
| Live agent execution | Gas City session runtime | Local or configured session backend | Process lifetime |
| Operational signals | Gas City events | List, stream, and cursor APIs | Local observation surface |
| Local run view | Gas City dashboard and API | Projection of retained bead lifecycle events, enriched with live and linked execution detail | Available with its local sources; not a governed team record |
.gc/ holds machine-local binding and runtime material. Portable pack definitions, customer repositories, and Beads data live at their own boundaries.
Commands define the security boundary
Factory configuration is trusted operator code. Agent commands, setup hooks, workflow scripts, automation checks, and pack commands can execute processes. The orchestrator strips inherited secret-looking environment variables in several paths, while operators can still pass credentials deliberately.
This architecture is inspectable and assumes reviewed, trusted configuration. Hostile code needs a separate sandbox boundary.
Use the trust-boundary reference when reviewing third-party packs, model endpoints, session runtimes, and network exposure. Provider permission modes and a sandboxed runtime can narrow risk, but the complete boundary includes every executable component.
The commercial extension starts at team operation
Team operation adds a boundary without changing this OSS component map. Beads Team Server preview is available through design partnerships as managed SaaS or self-hosted inside the customer’s VPC. It shares and governs team beads, remains executor-neutral, and captures organizational Runs in the organization’s shared location for the retention period the organization chooses. Gasworks is coming soon; it includes Beads Team Server and adds the shared multi-operator factory.
The OSS component map stays the same. The same customer-owned factory configuration can run on Gas City or Gasworks without conversion, while the team products add governance, shared operation, and retained history.
The enterprise orchestration guide covers placement and governance in detail. For short definitions, use the software factory glossary. For the category-level introduction, read Build an AI Software Factory.
Then follow the maintained tutorials in order: cities and projects, agents, formulas, Beads, and orders. The map should make those mechanics easier to place; the docs remain the operational source.
Related articles
- Build an AI software factory: Start with the category and customer-owned configuration before the component map.
- Why coding agents need a work graph: Go deeper on the relationship semantics inside the Beads data plane.
- Use Claude Code, Codex, and Gemini together: Explore the configured coding-agent boundary.
- An AI software factory in practice: See the public pack and provider seams operating across a real repository fleet.