---
id: surface.infotech.state-hub.api-config
name: State Hub API configuration
kind: app-config
summary: Runtime configuration for the Custodian State Hub API (bind host/port, database URL, environment mode).
owner: custodian
status: active
scope:
  allowed_layers: [product-default, company, environment, installation]
  default_layer: company
mutability: startup-time
security_class: operational
schema:
  type: object
  validator: ~/state-hub/config/schema.json
sources:
  - repo: state-hub
    path: Makefile
    role: product-default
  - repo: state-hub
    path: .env.example
    role: company-baseline
relations:
  consumed_by:
    - service.state-hub-api
  overrides: []
  depends_on_secret:
    - state-hub/database-url
  related_to:
    - surface.infotech.ops-bridge.tunnel-config
evidence:
  last_seen: '2026-06-26'
  discovery_method: manual
  change_log_ref: ATLAS-WP-0002-T01
---

# State Hub API configuration

The Custodian State Hub API (`http://127.0.0.1:8000`) reads its runtime
configuration at startup: bind host/port, database connection, and environment
mode. This surface **maps** that configuration — it does not duplicate the values.

- **Source of truth:** the `state-hub` repo (`make api` / `.env`); the database URL
  is a secret reference (`depends_on_secret`), never stored here.
- **Precedence:** product defaults in the Makefile, overridden by a company/env
  `.env`, optionally per-installation. Startup-time mutability — changes require an
  API restart (`make api`).
- **Consumers:** the State Hub API service; related to the ops-bridge tunnel config
  that exposes it to remote machines.

This is a seed example proving the surface-entry schema
([`../../docs/configuration-surface-schema.md`](../../docs/configuration-surface-schema.md)).
The broader Phase 1 seed is ATLAS-WP-0002-T03.