# Gas City Docs

- [Overview](https://docs.gascity.com/index.md): Gas City is the platform for building software factories — write down how a job gets done once, and an orchestrator runs it across a fleet of agents, reliably, without you in the loop.
- [Installation](https://docs.gascity.com/getting-started/installation.md): Install Gas City from Homebrew, a release tarball, or source.
- [Upgrading an Existing City](https://docs.gascity.com/getting-started/upgrading.md): Back up a city, upgrade Gas City and Beads, and run the one-time Beads schema migration when your city needs it.
- [Quickstart](https://docs.gascity.com/getting-started/quickstart.md): Create a city, add a rig, and route work in a few minutes.
- [Web dashboard](https://docs.gascity.com/getting-started/dashboard.md): The supervisor hosts a built-in web dashboard for all your cities.
- [How Gas City Works](https://docs.gascity.com/getting-started/how-gas-city-works.md): The orientation for Gas City — how it orchestrates fleets of agents, and the six primitives that compose into that orchestration.
- [Coming from Gas Town](https://docs.gascity.com/getting-started/coming-from-gastown.md): Map Gas Town's roles, mechanisms, layout, commands, and workflows onto Gas City's primitives.
- [FAQ](https://docs.gascity.com/getting-started/faq.md): Quick answers to the questions newcomers ask most — what Gas City adds over a single coding agent, what it runs on, and where to start.
- [Troubleshooting](https://docs.gascity.com/getting-started/troubleshooting.md): Common installation and setup issues and how to fix them.
- [Overview](https://docs.gascity.com/tutorials/index.md): The guided, sequential path that teaches the Gas City model by building one city up.
- [Tutorial 01 - Cities and Rigs](https://docs.gascity.com/tutorials/01-cities-and-rigs.md): Create a city, add a project as a rig, and sling your first work to an agent.
- [Tutorial 02 - Agents](https://docs.gascity.com/tutorials/02-agents.md): Define agents and use them to execute work.
- [Tutorial 03 - Sessions](https://docs.gascity.com/tutorials/03-sessions.md): See agent output, interact directly with agents, and learn the difference between on-demand and always-on sessions.
- [Tutorial 04 - Agent-to-Agent Communication](https://docs.gascity.com/tutorials/04-communication.md): How agents coordinate through mail, slung work, and hooks — without direct connections.
- [Tutorial 05 - Formulas](https://docs.gascity.com/tutorials/05-formulas.md): Capture how multi-step work should be done — steps, dependencies, variables, and control flow — in a reusable formula, then dispatch it to agents.
- [Tutorial 06 - Beads](https://docs.gascity.com/tutorials/06-beads.md): Understand the universal work primitive — the bead — that sessions, mail, and convoys are made of, that formulas materialize into when run, and learn to query and manipulate work items directly.
- [Tutorial 07 - Orders](https://docs.gascity.com/tutorials/07-orders.md): Trigger v2 formulas — and the orchestration the orchestrator drives — on a schedule, a condition, or an event, with no human in the loop.
- [Overview](https://docs.gascity.com/guides/index.md): Practical guides for common Gas City workflows.
- [Coming from Coding Agents](https://docs.gascity.com/guides/capabilities-for-coding-agent-users.md): How context, state, skills, history, messaging, roles, and identity work in Gas City — mapped to what you already know from coding agents.
- [Understanding Packs](https://docs.gascity.com/guides/understanding-packs.md): Learn what packs are, how imports work, and how Gas City turns reusable pack files into city behavior.
- [Understanding Formulas](https://docs.gascity.com/guides/understanding-formulas.md): How to think about formulas, choose a contract, and apply the major patterns.
- [Configuring an Agent](https://docs.gascity.com/guides/configuring-an-agent.md): The five axes of an agent — harness, model, upstream, transport, runtime — and how to set each in city.toml / agent.toml.
- [Harness Recipes](https://docs.gascity.com/guides/harness-recipes.md): Copy-paste upstream + model setup for each built-in harness — the fast path to swapping your CLI onto Gas City.
- [Create and Share Packs](https://docs.gascity.com/guides/shareable-packs.md): Create, import, and customize Gas City packs.
- [Find and Import Public Packs](https://docs.gascity.com/guides/registry-showcase.md): Find and import first-party packs from the public Gas City registry.
- [Configure the Gastown Pack](https://docs.gascity.com/guides/gastown-config-recipes.md): Task-oriented config overrides for running the Gastown pack on Gas City — register rigs, scale pools, swap providers, patch agents, and tweak prompts.
- [Use JSON from the gc CLI](https://docs.gascity.com/guides/using-json-from-gc.md): Use `gc --json` and `gc --json-schema` from scripts, agents, tests, and other software.
- [Connect an external client](https://docs.gascity.com/guides/connected-clients.md): Bring a chat, voice, or bot front end into a city conversation — send turns to an agent over HTTP and receive its replies on a callback.
- [Set Up a Multi-Agent Engineering Environment](https://docs.gascity.com/guides/multi-agent-engineering-environment.md): How to take a multi-human, multi-agent workflow you are already running by hand and give it a better home in Gas City.
- [Overview](https://docs.gascity.com/troubleshooting/index.md): Diagnosis walkthroughs and operational runbooks for a running city.
- [Diagnose a Failed gc start](https://docs.gascity.com/troubleshooting/gc-start-walkthrough.md): Match a failure symptom to its cause and resolution.
- [Recover from Dolt Bloat](https://docs.gascity.com/troubleshooting/dolt-bloat-recovery.md): Recover a Gas City beads store whose Dolt noms directory has grown out of proportion.
- [Clean Up bd Auto-Backups](https://docs.gascity.com/troubleshooting/bd-backup-cleanup.md): Reclaim space when bd's `.beads/backup/` directory grows large enough to threaten disk pressure.
- [Operate Managed-City Dolt Endpoints](https://docs.gascity.com/runbooks/managed-city-endpoints.md): Mental model, forbidden edits, sanctioned escape hatches, and recovery recipe for the city-level Dolt endpoint architecture.
- [Operate a Direct Hardened City from the gc CLI](https://docs.gascity.com/runbooks/remote-hardened-city.md): Stand up a self-hosted city that accepts remote writes over a signed X-GC-City-Write grant, wire a gc context to it, and run rig add --git-url and sling against it — with the threat posture and accepted residual risks stated up front.
- [Move a City's Infrastructure Classes onto Their Own Store](https://docs.gascity.com/runbooks/split-storage-classes.md): Config swap, one operator command, and the boot refusal that stands between them — plus what to check before, during, and after the cutover, and how to roll back while rolling back is still free.
- [Overview](https://docs.gascity.com/reference/index.md): Every Gas City reference page — generated docs, hand-maintained references, specifications, and internals.
- [CLI Reference](https://docs.gascity.com/reference/cli.md): Every gc command, flag, and example, generated from the CLI definitions.
- [Gas Town → Gas City Command Map](https://docs.gascity.com/reference/gastown-command-map.md): The closest `gc` or `bd` equivalent for each `gt` command, for operators migrating from Gas Town.
- [Gas City Configuration](https://docs.gascity.com/reference/config.md): Schema for city.toml — the deployment file for a Gas City instance.
- [Command Execution Trust Boundaries](https://docs.gascity.com/reference/trust-boundaries.md)
- [Supervisor REST API](https://docs.gascity.com/reference/api.md): The typed HTTP + SSE control plane exposed by the `gc` supervisor.
- [gc events Output Formats](https://docs.gascity.com/reference/events.md): Exact output formats emitted by `gc events`.
- [Schemas](https://docs.gascity.com/reference/schema/index.md): Machine-readable schema artifacts published with the Gas City docs.
- [Builtin Packs](https://docs.gascity.com/reference/system-packs.md): Built-in packs bundled with gc and composed via pinned imports.
- [Exec Session Provider](https://docs.gascity.com/reference/exec-session-provider.md)
- [Exec Beads Provider](https://docs.gascity.com/reference/exec-beads-provider.md)
- [Tmux Agent Slice (GC_AGENT_SLICE)](https://docs.gascity.com/reference/tmux-agent-slice.md)
- [herdr Session Provider](https://docs.gascity.com/reference/herdr-provider.md)
- [Overview](https://docs.gascity.com/reference/specs/index.md): Authoritative specifications for Gas City file formats and contracts.
- [Gas City Pack Specification](https://docs.gascity.com/reference/specs/pack-spec.md): Authoritative specification for Gas City pack format and loading semantics.
- [Gas City Formula Specification — v1](https://docs.gascity.com/reference/specs/formula-spec-v1.md): Authoritative specification for the formulas v1 contract.
- [Gas City Formula Specification — v2](https://docs.gascity.com/reference/specs/formula-spec-v2.md): Authoritative specification for the formulas v2 contract.
- [Gas City Service Protocol — v0](https://docs.gascity.com/reference/specs/service-protocol-v0.md): Authoritative specification for the generic hosted-service wire protocol used by gc login.
- [Gas City Identity Separator Contract — v1](https://docs.gascity.com/reference/specs/identity-separator-contract-v1.md): Authoritative specification for the qualified-identity encoding shared by gascity and beads.
- [Overview](https://docs.gascity.com/reference/internal/index.md): Internals-grade reference for operators and contributors who need to see under the hood.
- [Beads Storage Topology](https://docs.gascity.com/reference/internal/beads-topology.md): How a city and its rigs share one Dolt server while keeping each rig's beads logically isolated by prefix.

## OpenAPI Specs

- [openapi](/reference/schema/openapi.json)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.