providers.toml reference#

providers.toml is the explicit boundary among absent provider execution, deterministic sandbox execution, and chargeable live-provider execution. It defines the operator-approved set of provider targets, selects each target's active immutable revision, freezes operator-verified pricing, and applies the live-spend boundary only where real provider work is possible. It does not choose one provider or image size for every request: agents discover active targets at runtime and select among only this approved set.

For the primary operator flow, use the complete sandbox and Gemini and FLUX examples before consulting this field-by-field reference.

Potential charges: setting mode = "live" does not by itself perform work, but it prepares Gongbu to send requests to configured providers after the reviewed generation is active. Verify every provider value and price against current authoritative provider documentation.

Top-level fields#

schema_version#

This is the operator-owned source schema. The rendered Gongbu provider target and pricing documents use their own service-owned schema versions.

mode#

In disabled mode, omit catalog_version, maximum_spend_minor, live_spend_acknowledgement, every [[contract_bindings]] and [[targets]] table, and every [[pricing_rules]] table.

schema_version = 1
mode = "disabled"

Sandbox mode is generated by hubu stack init --mode sandbox. It requires a fixture-only target and synthetic frozen pricing, forbids live-spend fields and provider credentials, and renders through Gongbu's production execution path. The fixture adapter makes no external provider request.

schema_version = 1
mode = "sandbox"
catalog_version = "hubu-sandbox-v1"

Live mode requires the two spend fields plus at least one provider-contract binding. The shipped Gemini Developer API and FLUX targets must be introduced only through their frozen contracts. Multiple approved targets can coexist; agents discover opaque target_id values at runtime without submitting provider details. Generic integrations may still use the lower-level raw target format, subject to the composite rules below.

catalog_version#

Choose a label that identifies the exact prices and source date used to prepare the catalog, for example operator-verified-2026-08-24. Never reuse a catalog version for different content. The rendered catalog is canonicalized and digested so an execution can retain the exact pricing snapshot it used.

For exactly one provider contract with no raw target or pricing entries, omit this field and Hubu derives the contract's immutable pricing version. If supplied in that contract-only shape, it must equal the frozen version. A catalog with multiple contract bindings, or any contract-bound-plus-raw catalog, requires a new operator-owned immutable label.

maximum_spend_minor#

This is the managed Gongbu provider configuration's explicit upper spend boundary. It is not a provider price and does not create a Hubu budget. Use a conservative ceiling appropriate for this local profile.

For USD, 25 means 25 cents and 2500 means 25 dollars. Read pricing, authorization, holds, and settlement before selecting it.

live_spend_acknowledgement#

live_spend_acknowledgement = "I_ACKNOWLEDGE_LIVE_PROVIDER_SPEND"

The exact string is a deliberate safety gate, not a customizable description. It acknowledges that a valid active target can transmit chargeable work. It does not replace Hubu authorization, a budget, or the provider account's controls.

[[contract_bindings]]#

A contract-binding selection expands one named immutable contract into its exact provider target, adapter settings, and pricing rules. The shipped contracts can be bound independently:

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

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

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

contract must match a shipped contract exactly. credential names an opaque entry from credentials.toml; it never contains a key. Both fields are required and unknown fields are rejected.

Each contract freezes its own model, transport, retry, dimension, and pricing behavior; the binding cannot change any of it. The Gemini Developer API provider contract and the FLUX.2 provider contract are the canonical descriptions of those frozen values. Apply the shared live provider operations guide before activation.

Raw targets cannot duplicate or parallel a contract-bound provider/adapter route, and raw pricing cannot override its provider/model rules. Contracts for the same provider may share one credential alias; different providers must use distinct credential aliases and coordinates.

[[targets]]#

Each raw target records one immutable provider configuration revision for an internal workload/provider/adapter/model key. This format is for generic integrations; shipped Gemini and FLUX definitions are rejected here as contract bypasses. All raw target fields are required, including the booleans and settings table. Sandbox mode requires its generated fixture target, which omits credential because it has no external secret.

targets.provider_config_version#

Never reuse a version label with changed model, credential coordinates, activation flags, or adapter settings. Gongbu rejects a version reused with different canonical content.

targets.workload_type#

Defined by Gongbu's provider contract. Use image_generation for current image adapters. It is part of the stable target key and must be a valid identifier.

targets.provider#

Defined by the configured provider integration. Use the exact normalized provider ID expected by Gongbu and the matching pricing rules. This is not necessarily the provider's display name.

targets.adapter#

Defined by Gongbu's adapter registry. Current adapter IDs include:

• gemini_developer_image for the Gemini Developer API image path;
• flux2_api for the Flux 2 API adapter;
• ideogram_image for the Ideogram image adapter;
• fixture for test/local fixture execution only.

The adapter ID must agree with targets.settings.type. Do not infer one from provider marketing text.

targets.model#

Defined by the provider and selected adapter. Use the exact provider model ID sent on requests and repeat the identical value in each matching pricing rule. Verify availability, API version, and billing behavior with the provider.

targets.credential#

For [opaque.provider_image], use credential = "provider_image". Gongbu resolves the referenced service and account at execution time.

targets.active#

Required boolean. true makes this the active revision for its target key. Gongbu rejects more than one active revision for the same workload/provider/adapter/model key.

Use false to retain an immutable historical revision without selecting it for new work.

Every active, execution-enabled target with a complete adapter and pricing definition appears in the sanitized runtime catalog exposed through unified MCP. The catalog assigns an opaque target_id that remains stable when the operator rotates the target's credential, endpoint, or configuration revision. Agents select that ID and one of its advertised runtime image-size options; they never receive the target's credential reference or adapter transport settings.

targets.execution_enabled#

Required boolean. true permits a selected active revision to execute new work. false is an independent emergency/operational gate. A revision must be both active and execution-enabled to accept new work.

targets.settings#

Required tagged adapter settings. settings.type selects the service-owned settings schema and must agree with targets.adapter. settings.config contains the adapter-specific non-secret transport configuration.

[targets.settings]
type = "gemini_developer_image"

[targets.settings.config]
endpoint = "https://provider.example"
api_version = "v1"
timeout_ms = 30000

Fixture settings use only type = "fixture" and no config table. Fixture execution is not a live provider substitute.

Adapter setting fields#

The selected gongbu-server production validator is authoritative. Unknown adapter-setting fields are rejected.

targets.settings.type#

Required tag. Allowed current values are gemini_developer_image, flux2_api, ideogram_image, and fixture. It must match targets.adapter.

targets.settings.config.endpoint#

Required for every non-fixture adapter. Defined by the provider integration. Use the expected HTTPS API origin or base endpoint, not a documentation page. Verify the exact path behavior in the adapter's operational guide.

For flux2_api, the endpoint must be one of BFL's current documented API origins: https://api.bfl.ai, https://api.eu.bfl.ai, or https://api.us.bfl.ai. Paths, query strings, fragments, user information, explicit ports, and other origins are rejected before execution is enabled. This literal list governs configured generation POST endpoints. It is separate from provider-returned polling URLs, which may use api.bfl.ai or exactly api.<region-or-shard>.bfl.ai with one safe ASCII DNS label while retaining the fixed HTTPS path, query, operation-ID, port, fragment, and redirect checks.

targets.settings.config.api_version#

Required for every non-fixture adapter. Defined by the provider. Use the exact API version supported by the selected adapter and model.

targets.settings.config.timeout_ms#

Required invocation budget in milliseconds for every non-fixture adapter. The accepted range is 1..=270000 (up to 270 seconds). It covers the complete adapter operation described by its schema, which may include submission, polling, and artifact retrieval. For asynchronous FLUX work, Gongbu checkpoints one absolute deadline after submit; activity recovery and worker restart resume the same operation under that deadline and never create a fresh timeout budget.

targets.settings.config.max_retries#

Optional unsigned integer; defaults to 0. The only currently accepted value is 0 for every non-fixture adapter; Gongbu rejects nonzero values during provider-contract validation. Provider generation retries are not enabled even when an adapter exposes an idempotency header. Read-only polling of one durably checkpointed asynchronous operation is recovery, not a generation retry.

targets.settings.config.headers#

Optional map of non-secret HTTP headers, defaulting to empty. Header names are normalized by Gongbu. Do not place authorization values or provider secrets here; use targets.credential and the owning secret resolver.

targets.settings.config.approved_artifact_hosts#

Artifact-host allowlist for provider-referenced downloads. It defaults to empty when an adapter does not require it. It is required and must contain at least one host for ideogram_image.

For flux2_api, this list must be empty. FLUX delivery regions are dynamic, so Gongbu always applies its built-in delivery.<region>.bfl.ai matcher with one safe ASCII DNS label instead of accepting static host pins or configurable wildcards. Extra labels, IDNA labels, lookalikes, URL syntax, and suffix matches are rejected. These artifact hosts never receive the BFL x-key credential.

targets.settings.config.poll_interval_ms#

Optional for flux2_api; defaults to 500. It is the delay between GET status polls for one durably checkpointed provider operation and remains bounded by the original overall timeout_ms. It never authorizes another generation submission.

targets.settings.config.idempotency_header#

Optional for flux2_api. Name of the provider-supported idempotency header. Configure it only when the provider documents durable idempotency semantics for the selected operation; it is not an arbitrary client header.

[[pricing_rules]]#

Live mode uses pricing catalog schema version 2 exclusively. Every rule is immutable within catalog_version and matches one provider/model plus an optional selector.

pricing_rules.rule_id#

Required unique, non-empty stable identifier. Choose a descriptive immutable ID such as provider-model-1k. Duplicate IDs are rejected.

pricing_rules.provider#

Required normalized provider ID. It must exactly match the target's provider value.

pricing_rules.model#

Required normalized model ID. It must exactly match the target's model value.

pricing_rules.currency#

Required currency code. Schema version 2 currently supports USD; it is normalized to uppercase.

pricing_rules.selector#

Optional inline table used to distinguish prices for the same provider/model. Current image pricing supports selector = { image_size = "1k" }, with normalized 1k, 2k, or 4k values.

A selector-qualified rule must contain exactly one image price component. Define one unambiguous rule for every enabled image size. Two rules with the same provider, model, and selector are rejected.

pricing_rules.selector.image_size#

Defined by the provider's billable resolution tier and the normalized request contract. Allowed current values are 1k, 2k, and 4k after normalization. Do not use pixel dimensions unless the provider contract maps them to one of these selectors.

For the flux2_api adapter, the selectors map to the certified exact BFL output dimensions defined in the FLUX.2 provider contract. An enabled FLUX target must have one selector-qualified, operator-verified pricing rule for each of the three certified presets; a flat rule or partial pricing set is not enough. The image_size selector is durable pricing and replay evidence and is never sent to BFL.

pricing_rules.components#

Required non-empty array of price component tables. Each unit may appear at most once in a rule. Multi-component rules represent pricing such as one image charge plus input/output token charges.

pricing_rules.components.unit#

Required. Allowed values:

• image — quantity of generated images;
• input_token — billable input-token quantity;
• output_token — billable output-token quantity.

pricing_rules.components.rate_numerator_minor#

Required non-negative integer numerator of the exact price in currency minor units per unit. Do not pre-round a fractional provider rate.

pricing_rules.components.rate_denominator#

Required positive integer denominator of the exact price in currency minor units per unit.

For a provider price of USD $0.067 per image, cents are the minor unit and the exact rate is 6.7 cents:

components = [
  { unit = "image", rate_numerator_minor = 67, rate_denominator = 10 },
]

For USD $2.50 per million input tokens, the rate is 250 cents per 1,000,000 tokens:

components = [
  { unit = "input_token", rate_numerator_minor = 250, rate_denominator = 1000000 },
]

Gongbu computes an exact rational estimate and rounds it up once to micro-units (10⁻⁶ of the currency) for the authorization amount. Settlement preserves the final exact provider cost with this complete frozen pricing snapshot and converts it to budget micro-units once, as defined in precise external cost and budget conversion. Verify both the provider's unit and whether quoted prices include every billable component.

Matching and ambiguity rules#

• Every selectable live target needs a pricing rule for its exact provider/model and request selector.
• Rule IDs are globally unique within the catalog.
• Provider/model/selector combinations are unambiguous.
• Image selectors require one image component.
• Component units cannot repeat within one rule.
• Rates cannot be negative and denominators must be positive.
• Unsupported currencies, units, selectors, or old flat pricing shapes are rejected.

After changing providers.toml#

Run doctor and render. Review the changed source files, target versions, catalog version, and affected components. Stop the whole managed stack before activating the reviewed generation. Rendering or activation never contacts a provider or performs provider work; later execution through an active, execution-enabled live target may incur charges.