stack.toml reference#

stack.toml selects compatible binaries, assigns lifecycle ownership, separates persistent state, configures Temporal, and defines bounded runtime policy. It never selects an execution account or agent and never contains credential values or provider pricing.

Source of truth: edit this file, then run hubu stack doctor. Do not edit rendered JSON generations.

Top-level fields#

schema_version#

Selects the operator-owned source schema. All three source files must use a supported version. Unknown fields are rejected rather than ignored.

schema_version = 1

allow_development_builds#

Set true only when every selected binary is an unstamped local development build. Packaged or stamped binaries must remain on false. This is not a compatibility bypass: selected binaries must still share product, source, and executor-contract provenance.

[binaries]#

All binary fields are safe absolute paths to existing executable files. stack init fills a path only when it safely discovers the executable. Selected packaged binaries must come from one release lineage.

binaries.hubu#

[binaries]
hubu = "/Users/alice/.local/bin/hubu"

binaries.hubu_server#

Required when hubu.ownership = "managed"; omit it for external Hubu. It identifies the hubu-server binary whose production validator and lifecycle entry point the stack uses.

binaries.gongbu_server#

Required when gongbu.ownership = "managed"; omit it for external Gongbu. Gongbu remains a separate process and owns its provider execution, worker, database, and artifacts.

binaries.hubu_unified_mcp#

Required for every profile. It identifies the only supported agent-facing MCP binary. The stack prepares its handoff configuration but never starts or supervises the client-owned stdio process.

Execution attribution#

Schema version 1 accepts a legacy [identity] block only for source-file compatibility, but current rendering ignores it. New profiles must omit the block. Stack startup selects no execution account or agent. For each new execution, Hubu spend authorization supplies authoritative account and agent attribution and Gongbu persists that immutable snapshot.

identity.account_id#

Deprecated compatibility field. When present, it must be a non-empty string, but rendering ignores it. Do not add it to new profiles; Hubu authorization supplies the authoritative execution account.

identity.agent_id#

Deprecated compatibility field. When present, it must be a non-empty string, but rendering ignores it. Do not add it to new profiles; Hubu authorization supplies the authoritative execution agent.

[hubu]#

hubu.ownership#

Choose managed for the standard local installation. Choose external only when another process or operator owns hubu-server. See managed versus external ownership.

hubu.endpoint#

endpoint = "http://127.0.0.1:8787"

Even external services are local in schema version 1. For managed Hubu, the host and port must match hubu.listen.

hubu.listen#

Required for managed Hubu and ignored for lifecycle ownership when Hubu is external. Use an explicit loopback socket such as 127.0.0.1:8787. It must not conflict with Gongbu or managed Temporal ports.

hubu.database_path#

Required for managed Hubu. Use a safe absolute path dedicated to the Hubu SQLite database. It must not overlap Gongbu state, Gongbu artifacts, Temporal data, or unified-MCP operation state.

hubu.log_file#

Optional absolute path for managed Hubu structured logs. Use a file distinct from all database and directory resources. If omitted, lifecycle log behavior follows the generated server configuration and launcher behavior.

[gongbu]#

gongbu.ownership#

Choose managed for the standard local stack. Managed Gongbu owns its Temporal worker and, in managed_local Temporal mode, the Temporal child process. External Gongbu retains authority for its own provider and artifact configuration.

gongbu.endpoint#

Required explicit loopback http:// origin. For managed Gongbu it must match gongbu.listen. Hubu and the unified MCP client use the versioned public interface at this origin; they never open Gongbu's database.

gongbu.listen#

Required for managed Gongbu. Use a distinct loopback socket such as 127.0.0.1:8788.

gongbu.database_path#

Required for managed Gongbu. Use a safe absolute path dedicated to Gongbu's SQLite database. Never reuse the Hubu database or place it inside the artifact or Temporal directories.

gongbu.artifact_root#

Required for managed Gongbu. This safe absolute directory stores Gongbu-owned execution artifacts. Keep it separate from every database, log, Temporal, and unified-MCP state path.

gongbu.log_file#

Optional absolute path for managed Gongbu structured logs. Keep it separate from all managed databases and directories.

[temporal]#

The Temporal section is required when Gongbu is managed. It is not a second worker configuration: Gongbu always owns and starts its worker.

temporal.mode#

managed_local lets Gongbu manage a local Temporal service using the selected CLI binary. external connects to an already managed Temporal deployment. See the Temporal decision guide.

temporal.binary_path#

Required only for managed_local. Use the safe absolute path to the installed Temporal CLI executable. The selected CLI is probed with a bounded command; Hubu does not download it.

temporal.expected_cli_version#

Required only for managed_local. Copy the exact version reported by the selected Temporal CLI. Pinning prevents an unexpected local upgrade from silently changing lifecycle behavior.

temporal.data_path#

Required only for managed_local. Use a safe absolute directory dedicated to Temporal state. It must not overlap Hubu state, Gongbu state, artifacts, or logs.

temporal.rpc_port#

Required only for managed_local. Integer TCP port for local Temporal RPC. Default starter value: 7233. It must differ from the UI port and every managed Hubu/Gongbu socket.

temporal.ui_port#

Required only for managed_local. Integer TCP port for the local Temporal UI. Default starter value: 8233. It must differ from the RPC port and every managed backend socket.

temporal.address#

Required only for external. Supply the external Temporal RPC address, for example http://127.0.0.1:7233. The external operator retains lifecycle and state authority.

temporal.namespace#

Required for either Temporal mode. Defined by Temporal. The starter uses default; use another namespace only when it already exists and the selected Temporal deployment expects it.

temporal.task_queue#

Required for either Temporal mode. Chosen by the operator and Gongbu deployment. Gongbu server and worker must use the same queue. The starter uses gongbu-local-executions.

temporal.ui_url#

Optional display URL for operator navigation. It is not used as the RPC address and does not grant lifecycle authority.

[runtime]#

The whole runtime section is optional because every field has a safe schema default. stack init writes the defaults explicitly so operators can review them. These values are rendered into managed server configuration and validated by the selected production binaries.

runtime.hubu_startup_policy#

String passed to Gongbu's Hubu dependency policy. Default: "wait". Keep wait for the supported local profile so Gongbu bounds startup while Hubu becomes ready.

runtime.hubu_startup_timeout_ms#

Unsigned integer milliseconds Gongbu allows for Hubu startup readiness. Default: 30000.

runtime.recovery_delays_seconds#

Array of unsigned integer seconds used for execution recovery scheduling. Default: [30, 120, 600]. Changing it affects recovery timing, not provider retry safety.

runtime.temporal_startup_timeout_ms#

Unsigned integer milliseconds allowed for managed Temporal startup readiness. Default: 30000.

runtime.dependency_check_interval_ms#

Unsigned integer milliseconds between dependency readiness checks. Default: 5000.

runtime.worker_drain_timeout_ms#

Unsigned integer milliseconds Gongbu allows its worker to drain during graceful shutdown. Default: 30000.

runtime.max_artifacts_per_execution#

Unsigned integer maximum number of accepted artifacts for one execution. Default: 4.

runtime.max_encoded_bytes#

Unsigned integer maximum total encoded artifact bytes. Default: 20971520 (20 MiB).

runtime.max_decoded_bytes#

Unsigned integer maximum total decoded artifact bytes. Default: 104857600 (100 MiB).

runtime.max_width#

Unsigned integer maximum decoded image width in pixels. Default: 16384.

runtime.max_height#

Unsigned integer maximum decoded image height in pixels. Default: 16384.

runtime.log_level#

Logging level passed to managed server configuration. Default: "info". Use only values accepted by the selected server release.

runtime.log_format#

Logging format passed to managed server configuration. Default: "text". Use the server-supported format expected by the operator's log workflow.

After changing stack.toml#

Run:

hubu stack doctor --profile /absolute/path/to/profile
hubu stack render --profile /absolute/path/to/profile

Review the changed source files and affected components. When a generation is already active, stop the whole managed stack, activate the reviewed generation, and start it. If the generated client handoff changes, rerun hubu init codex --stack-profile ... and restart Codex after the backends are ready.