Local stack configuration reference#

Schema version 1 is the operator-owned configuration contract for the local Hubu stack. This reference explains what every field means, where its value comes from, and what must happen after it changes.

Start safely: use the provider-disabled example for a first installation. Disabled mode omits provider targets, prices, spend ceilings, and the live-spend acknowledgement. It cannot perform live provider work.

The three source files#

hubu stack init creates three TOML files. They are the source of truth; generated runtime JSON is not an editing surface.

File	Controls	Typical value sources	Detailed reference
`stack.toml`	Binaries, topology, Temporal, state paths, lifecycle, and runtime limits	Hubu discovery and explicit operator choices	`stack.toml`
`credentials.toml`	Provider references plus optional external-service credential overrides	Gongbu/provider setup; managed service references are derived internally	`credentials.toml`
`providers.toml`	Disabled/live mode, provider targets, frozen pricing, spend ceiling, and the live-spend gate	Provider documentation and explicit operator approval	`providers.toml`

All three files use schema_version = 1 and reject unknown fields. A value that parses as TOML can still be incomplete or unsafe; always run doctor before rendering.

Value-source labels#

Each field reference identifies who supplies the value:

Label	Meaning
Discovered by Hubu	`stack init` may fill the value when it can prove a safe local fact.
Generated by Hubu	A Hubu command creates the identifier, path, or reference. Copy the printed value exactly.
Chosen by the operator	The value expresses topology, risk, lifecycle, or spend intent. Hubu must not invent it.
Defined by Gongbu	The execution plane owns the value or its validation contract.
Defined by Temporal	The installed or external Temporal deployment supplies the value.
Defined by the provider	Verify the value against current authoritative provider documentation.
Credential reference	Store only a path or opaque service/account coordinate, never the secret value.

Configuration lifecycle#

The supported first-run flow is:

stack init → operator edit → stack doctor → stack start

stack start runs doctor and render when needed, then starts missing managed components in dependency order. It never starts the client-owned hubu-unified-mcp process.

Later source changes use a reviewable two-phase flow:

operator edit → stack doctor → stack render → review plan
             → stack stop → stack activate → stack start

There is no hubu stack restart command. Do not edit generated generations or generated/active-manifest.json.

Security boundary#

Never put any of these values in the TOML files:

bearer tokens;
provider API keys;
approval or reconciliation capabilities;
credential-file contents;
secrets copied out of Keychain.

credentials.toml contains references only. For managed services, omitted references are derived internally and may remain pending until stack start. For explicit external references, the renderer validates shape and existence. It never reads, copies, compares, or serializes credential values.

Keep Hubu and Gongbu separate even though the profile coordinates them. They retain separate processes, databases, credentials, provider execution, artifacts, and failure domains. They communicate through the versioned executor contract.

Choose the right reading path#

First local evaluation#

Read the provider-disabled example.
Use the stack.toml reference for topology and runtime boundaries.
Leave managed service credential fields omitted; use the credentials.toml reference only for provider references or external-service overrides.
Set only schema_version = 1 and mode = "disabled" in providers.toml.
Run doctor and follow the reported field paths.

Live provider preparation#

Complete and validate the local topology first.
Read provider targets and adapter settings.
Read pricing, authorization, holds, and settlement.
Verify provider identifiers, endpoints, supported models, prices, and billing units with the provider.
Use the live-provider example as structure, not as current provider data.

External or customized topology#

Read managed versus external ownership and Temporal mode, then use the complete field references. External ownership changes lifecycle authority; it does not merge Hubu and Gongbu.

Lifecycle impact lookup#

Changed source	Typical affected consumers	Required workflow
Comment only	No runtime component	Doctor and render may produce a new source digest; review the plan.
Binary or topology field	Launcher and the selected backend	Doctor → render → whole-stack stop → activate → start.
New Hubu agent registration	Hubu governance state only	No render, activation, stop, restart, or Gongbu configuration change.
Managed service credential	Internal lifecycle state and MCP handoff	No source edit; start creates or reuses it. Managed rotation is a separate lifecycle operation.
External/provider reference path or coordinate	Owning backend and possibly MCP handoff	Create the replacement reference first, then doctor → render → stop → activate → start.
Provider target, settings, or pricing	Gongbu	Doctor → render → stop → activate → start.
Runtime or logging policy	Managed process configuration	Doctor → render → stop → activate → start.

Doctor and render report the exact affected components. Treat their redacted plan as authoritative for the selected release.

Cross-file relationships#

Hubu spend authorization
   │ authoritative account + agent snapshot per new execution
   ▼
Gongbu execution record

credentials.toml [opaque.provider_image]
                         │ referenced by key
                         ▼
providers.toml [[targets]].credential
                         │ selects provider/model revision
                         ▼
providers.toml [[pricing_rules]]
                         │ bounds authorized execution
                         ▼
maximum_spend_minor → authorization → budget hold → settlement

The opaque table name is a local reference key. Its service and account values are Gongbu-owned Keychain coordinates. A provider target refers to the local key, never to a raw provider secret.

Reference index#

Versioning#

This reference documents source schema version 1 for the current Hubu release line. Use the documentation version that matches the installed binaries. A future incompatible source shape must use a new schema version rather than silently changing the meaning of version 1.

Run each selected binary with --version to inspect its safe version metadata. Packaged profiles require Hubu, Gongbu, the unified MCP server, and managed server binaries from one compatible release lineage.