credentials.toml reference#

credentials.toml never contains credential values. For the normal managed local stack it contains only the schema version plus any provider references:

See the complete Gemini + FLUX example for copyable provider references and the exact macOS Keychain Where/Account mapping.

schema_version = 1

Hubu selects private profile-owned locations for its authentication, approval, and reconciliation capabilities. The final managed hubu-server creates or reuses those capabilities during stack start; there is no preliminary server. After Hubu is ready, a Gongbu-owned bootstrap creates or reuses its internal Hubu handoff and caller capabilities before Gongbu starts. Users do not choose, copy, or configure those locations.

The current managed implementation stores these capabilities in private files under profile state. That is an internal compatibility detail, not a promise that the managed contract will remain file-based.

Never paste a bearer token, API key, approval capability, reconciliation capability, or credential-file content into this file.

Top-level field#

schema_version#

All three source files must use a supported source schema version. Unknown fields are rejected.

[files] advanced and external overrides#

The [files] table is absent for the standard managed-local profile. It exists for external-service topology and compatibility overrides where an operator must supply a reference owned outside the managed bootstrap:

[files]
hubu_auth = "/absolute/path/to/hubu.auth-token"
hubu_approval = "/absolute/path/to/hubu.approval-token"
hubu_reconciliation = "/absolute/path/to/hubu.reconciliation-token"
gongbu_caller = "/absolute/path/to/gongbu.caller-token"

All configured paths must be safe and absolute, must identify distinct capabilities, and must never point at the source TOML or backend databases. Every explicit override is operator-owned and must provide an existing readable regular file. Only omitted, profile-derived managed destinations may be absent before first start and created by the final Hubu process.

files.hubu_auth#

Required when Hubu is external. This is the client-side authentication bearer used by the Hubu CLI and unified MCP protected calls. For a managed Hubu it is normally omitted and derived internally.

After the profile has an active generated handoff, the Hubu CLI resolves this file together with the profile's endpoint and other human capability files. Selecting a profile therefore overrides ambient CLI endpoint and token variables as one atomic connection context. An explicit global --url opts out of profile resolution and uses manual environment/file credentials.

files.hubu_approval#

Required when Hubu is external. This is the human approval capability and must remain distinct from ordinary Hubu authentication. For a managed Hubu it is normally omitted and derived internally.

files.hubu_reconciliation#

Required when Hubu is external. Reconciliation authority is separate from authentication and approval authority. For a managed Hubu it is normally omitted and derived internally.

files.gongbu_caller#

Required when Gongbu is external, and when a managed Gongbu uses the explicit opaque bootstrap overrides below. This is the unified MCP client's caller capability; it authenticates the installation/service and carries no account or agent identity. For the normal managed handoff it is omitted and created at an internally selected location.

Rendering never reads, copies, compares, hashes, logs, or serializes the values behind these file references.

[opaque.<key>]#

Opaque tables name Gongbu-owned secret coordinates. The table key is a local reference from providers.toml; it is not itself a secret.

[opaque.provider_image]
service = "gongbu.provider.example"
account = "local-image-provider"

The renderer checks the reference shape but never resolves the value. Gongbu owns secret loading and provider use.

opaque.<key>.service#

opaque.<key>.account#

Reserved managed-Gongbu override references#

The standard managed profile omits both reserved tables. The renderer derives fixed internal references and the launcher invokes Gongbu's managed bootstrap.

Declaring either reserved table opts into the advanced externally provisioned Gongbu path. In that mode both tables and files.gongbu_caller are required, the launcher does not perform the managed handoff, and Gongbu resolves the opaque references through its normal secret backend.

opaque.gongbu_hubu#

Names the capability Gongbu uses to call Hubu's executor lifecycle interface.

[opaque.gongbu_hubu]
service = "gongbu.hubu"
account = "local-stack"

opaque.gongbu_caller#

Names the server-side capability Gongbu expects from its installation caller. It and files.gongbu_caller are references on opposite sides of the same authentication boundary. The renderer does not prove that their underlying values match.

Provider credential references#

Live providers.toml targets use an opaque table key:

# credentials.toml
[opaque.provider_image]
service = "gongbu.provider.example"
account = "image-production"

# providers.toml
[[targets]]
credential = "provider_image"

Every referenced key must exist and contain non-empty service and account fields. Multiple targets may intentionally share a credential, but provider selection and revision semantics remain explicit in each target.

FLUX provider contract credential#

For hubu.flux-2-pro.text-to-image/v1, create the BFL API key yourself and store it with the macOS Keychain Access app. Never paste, print, export, or shell the key, and never place it in an environment variable, command, source file, log, SQLite database, or support conversation. Hubu records only the operator-chosen service/account lookup pair:

[opaque.bfl_flux2_pro]
service = "operator-owned BFL Keychain service"
account = "operator-owned BFL Keychain account"

The corresponding [[contract_bindings]] entry uses credential = "bfl_flux2_pro". Doctor asks Keychain only whether that item is present; it does not request or compare its value and it does not call BFL. Apply the shared live provider operations guide, then read the FLUX.2 provider contract before enabling live mode.

Rotation#

Managed credentials are not rotated by editing their hidden paths. The current start sequence creates or reuses them and fails closed if Gongbu handoff state conflicts. A future managed rotation or non-file storage change can replace that internal mechanism without adding locations to the source profile.

For an advanced external file reference, do not overwrite a value in place:

1. Create a private replacement credential file.
2. Change its absolute path in credentials.toml.
3. Run doctor and render, then review the affected components and generation.
4. Stop the whole managed stack, activate the reviewed generation, and start.
5. Keep the previous credential until the new generation is verified.
6. Rerun hubu init codex --stack-profile ... when the handoff changes.

For an opaque reference, create a new secret item or coordinate according to Gongbu's credential procedure, then change its service or account. Never copy secret values into TOML.

Common mistakes#

• Adding [files] to a normal managed profile even though the launcher owns location selection.
• Pasting a token after hubu_auth = instead of an absolute file path.
• Reusing one capability for authentication, approval, and reconciliation.
• Configuring only one of the two reserved Gongbu override references.
• Assuming files.gongbu_caller and opaque.gongbu_caller are interchangeable.
• Referring to [opaque.provider_image] as credential = "opaque.provider_image"; use credential = "provider_image".