Complete local stack examples#

Use a separate profile directory for each outcome. hubu stack init writes the complete topology and source files for that outcome; do not copy a hand-written stack.toml between modes.

Keep sandbox and live profiles separate#

Do not switch one profile back and forth between sandbox and live. Separate profiles isolate provider credentials, spend acknowledgement, frozen catalogs, generated generations, runtime state, databases, artifacts, and logs. Each flow below explicitly selects its new profile immediately after initialization so later hubu stack commands use the intended configuration. Check the current selection at any time with:

hubu stack profiles

This makes the non-billable default easy to recover, keeps live credentials out of sandbox state, and makes the active spend boundary visible in the selected profile path. Stop the active managed stack before selecting and starting another profile when their default local ports overlap.

Sandbox: complete stack without live spend#

Sandbox is the recommended first profile and a zero-edit outcome. It runs the real Hubu, Gongbu, and Temporal boundaries but replaces the external provider edge with a deterministic, non-billable fixture:

hubu stack init --mode sandbox --install-temporal \
  --profile /absolute/path/to/hubu-sandbox
hubu stack select --profile /absolute/path/to/hubu-sandbox
hubu stack doctor

Initialization writes the complete managed topology, fixture target, and synthetic frozen pricing. The generated profile contains no provider credential, live-spend ceiling, or live-spend acknowledgement. When doctor reports ready_to_render, the profile is ready for hubu stack start without an operator edit.

Live: Gemini Developer API and FLUX.2#

Use live mode only in its own profile after the sandbox profile is healthy. With the four Hubu binaries and the Temporal CLI discoverable, initialization writes the complete managed stack.toml; the operator edits only the provider references and selections shown below:

hubu stack init --mode live --install-temporal \
  --profile /absolute/path/to/hubu-live
hubu stack select --profile /absolute/path/to/hubu-live

This example enables both shipped Gemini Developer API image contracts and the FLUX.2 Pro contract. Live execution can incur provider charges after this profile is validated, rendered, activated, started, and selected for a governed request.

Store two provider credentials in macOS Keychain#

Create the Google AI Studio API key and BFL API key with Keychain Access. The two items must use different lookup coordinates. In Hubu configuration:

• service maps to the Keychain Access Where field;
• account maps to the Keychain Access Account field; and
• a matching Name alone is insufficient because Gongbu looks up the exact Where and Account pair.

Use the same non-secret Where and Account values below. Hubu and Gongbu must run as the macOS user allowed to access these Keychain items. Doctor checks that each exact reference exists without retrieving or printing its value.

Edit credentials.toml#

credentials.toml contains lookup coordinates only, never credential values:

schema_version = 1

[opaque.google_gemini]
service = "operator.google.gemini"
account = "gemini-image"

[opaque.bfl_flux]
service = "operator.bfl.flux"
account = "flux-image"

The opaque table names are local aliases. Both Gemini contracts intentionally share google_gemini; FLUX uses the separate bfl_flux alias and Keychain item.

Edit providers.toml#

All fields shown here are required for this three-contract live catalog. The catalog version is an immutable operator-owned label for this exact composite; use a new label if any selected contract or frozen price changes.

schema_version = 1
mode = "live"
catalog_version = "operator-gemini-flux-2026-09-03-v1"

# Positive USD cents approved as this profile's local spend ceiling.
maximum_spend_minor = 25
live_spend_acknowledgement = "I_ACKNOWLEDGE_LIVE_PROVIDER_SPEND"

[[contract_bindings]]
contract = "hubu.gemini-3.1-flash-lite-image.text-to-image/v1"
credential = "google_gemini"

[[contract_bindings]]
contract = "hubu.gemini-3.1-flash-image.text-to-image/v1"
credential = "google_gemini"

[[contract_bindings]]
contract = "hubu.flux-2-pro.text-to-image/v1"
credential = "bfl_flux"

Each versioned contract expands to an immutable target and its exact pricing; do not reproduce these shipped integrations as raw [[targets]] or [[pricing_rules]] tables:

These prices are frozen versioned configuration, not timeless provider price claims. The Gemini contract and FLUX.2 contract document their source dates, capabilities, dimensions, transport, and recovery policy. If current provider terms no longer match, keep this profile inactive until a new contract is shipped.

Validate with doctor#

hubu stack doctor is the authoritative validation path for the whole profile:

hubu stack doctor

Follow its field-specific diagnostics until it reports ready_to_render. Doctor verifies the source shape, credential-reference existence, contract and target expansion, selector-complete rational pricing, and live-spend gate without printing a credential or contacting a provider. For a new profile, doctor reports production_validated = false until a generation has been rendered. Render it, then rerun doctor so its contract readiness report confirms the rendered generation passed production validation:

hubu stack render
hubu stack doctor

Use --json for the same authoritative results in automation. Do not replace doctor with a manual live-profile checklist. Review the generation before activation as described in Managing a local stack.

Advanced raw-provider configuration, external Hubu/Gongbu/Temporal ownership, and provider-specific recovery details remain available in the configuration decisions, provider reference, and live provider operations.

Advanced and legacy configurations#

Decisions-only is a future advanced concept and is not currently supported. Both supported modes use Gongbu and the existing reservation-and-settlement accounting lifecycle. There is no supported executor = "none" configuration. Custom executors on the v4.5 contract remain an advanced integration point rather than a starting stack mode.

Legacy local-stack is accepted as a deprecated alias for live. Change mode = "local-stack" to mode = "live" in an existing full-stack profile; new profiles use the canonical name. Existing hubu-only profiles are rejected with migration guidance. Preserve their files and create a separate sandbox or reviewed live profile; do not automatically switch them to billable execution.