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: hubu stack init --mode sandbox creates the complete local ecosystem with real internal governance and execution communication while replacing only the external provider edge with a deterministic, non-billable fixture.

Start with the complete local stack examples for the generated sandbox outcome, one working Gemini + FLUX live profile, and the recommended separate-profile switching model.

The three source files#

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

Stack mode	Components and outcome
`sandbox`	Managed Hubu, Gongbu, and Temporal with fixture-only external provider behavior.
`live`	Managed Hubu, Gongbu, and Temporal with one or more operator-approved live targets.

Both modes start Gongbu by default and use reservation-and-settlement accounting. Decisions-only is a future advanced concept, not a supported configuration. Legacy local-stack is a deprecated alias for live. Legacy hubu-only profiles are rejected with migration guidance; create and review a separate sandbox or live profile rather than silently changing an existing spend boundary.

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`	Sandbox/live provider 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 --mode MODE → review remaining operator decisions → 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#

Run hubu stack init --mode sandbox --install-temporal on macOS, or install Temporal independently before initialization.
Hubu discovers installed stack binaries and the Temporal CLI, including its exact version.
Run doctor and follow only the remaining dependency diagnostics.
Start the profile; no provider credential, network request, or live-spend acknowledgement is involved.

Live provider preparation#

Create a separate live profile; do not convert the sandbox profile in place.
Copy the operator-edited files from the complete Gemini + FLUX example.
Follow the shared live provider operations guide for credentials, governance, pricing, spend, retry, reconciliation, artifacts, and qualification.
For the FLUX provider contract, follow the provider-specific FLUX.2 provider contract.
For a generic target, 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.

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. Production profiles require Hubu, Gongbu, the unified MCP server, and managed server binaries from one compatible, release-stamped lineage. This includes binaries installed from an exact source release; they keep allow_development_builds = false.