Local stack quick start#

Use this guide to initialize, start, inspect, and connect a local Hubu stack. For configuration fields and design choices, use the public schema-version-1 configuration reference.

Check the binaries#

Install hubu, hubu-server, gongbu-server, and hubu-unified-mcp from the same verified Hubu release, put them on PATH, and confirm that they report the intended release:

for binary in hubu hubu-server gongbu-server hubu-unified-mcp; do
  command -v "$binary"
  "$binary" --version
done

If the profile will use managed-local Temporal, install the version-pinned Temporal CLI described in the Temporal decision guide.

Initialize and select a profile#

Choose an absolute profile path, initialize it, and select it for later stack commands:

profile=/absolute/path/to/profile
hubu stack init --profile "$profile"
hubu stack select --profile "$profile"

Initialization creates starter files without overwriting existing files or starting services:

PROFILE_ROOT/
  README.md
  stack.toml
  credentials.toml
  providers.toml
  generated/
  state/
    credentials/
      .gitignore

The three TOML files are the editable sources. A provider-disabled managed profile normally leaves credentials.toml at its generated schema-only content. Do not edit generated/ or state/.

Complete and validate the profile#

Follow the comments in the starter files and use the detailed reference when a choice is unclear:

File	What to choose	Detailed reference
`stack.toml`	Binaries, managed or external services, Temporal, and local paths	`stack.toml`
`credentials.toml`	Provider references or advanced external-service overrides	`credentials.toml`
`providers.toml`	Disabled or live mode, targets, pricing, and spend ceiling	`providers.toml`

For a first local evaluation, start with the provider-disabled example. Never put bearer tokens, provider API keys, or other raw secrets in the TOML files. Live provider execution can incur charges.

Check the profile and follow the reported field paths until it is ready:

hubu stack doctor

Doctor is read-only. An explicit --profile "$profile" can override the saved selection for any one stack command.

Start and inspect the stack#

Start the stack, then confirm that its managed components are ready:

hubu stack start
hubu stack status

stack start runs doctor and render when needed. For a fully managed profile, it starts the final Hubu process, completes Gongbu's managed credential bootstrap, and starts Gongbu and its managed Temporal runtime. The client-owned hubu-unified-mcp process is not part of the managed stack.

Connect Codex#

After the stack is ready, write the managed MCP configuration:

hubu init codex --stack-profile "$profile"

Restart Codex so it launches the unified MCP process with the new handoff. See Unified MCP setup for discovery and compatibility details.

Routine operations#

# List profiles and show machine-readable status.
hubu stack profiles
hubu stack status --json

# Read launcher-owned logs.
hubu stack logs --component all --lines 200
hubu stack logs --component gongbu --execution-id EXECUTION_ID

# Gracefully stop the complete managed stack.
hubu stack stop

There is no hubu stack restart command. For an unchanged unhealthy or partial managed stack, run hubu stack stop, then hubu stack start.

Apply a configuration change#

Render and review a changed profile before activating it:

hubu stack doctor
hubu stack render
# Review the generation ID, changed files, and affected components.
hubu stack stop
hubu stack activate --generation GENERATION_ID
hubu stack start
hubu stack status

For rollback, first restore the exact operator-owned TOML and compatible binaries for the retained generation, then run:

hubu stack generations
hubu stack render
hubu stack stop
hubu stack rollback --generation PRIOR_GENERATION_ID
hubu stack start
hubu stack status

If the rendered plan reports hubu-unified-mcp-client-config as affected, rerun hubu init codex --stack-profile "$profile" after the stack is ready and restart Codex.

The active-profile change guide explains staging, credential-reference changes, and rollback requirements.

More detail#

Use the managed lifecycle commands above for the persistent execution plane.