Projects and configuration

hum separates machine-wide project discovery from repository-owned service configuration.

Global project registry

The default registry is $XDG_CONFIG_HOME/hum/config.yaml or ~/.config/hum/config.yaml:

version: 1
projects:
  storefront:
    config: ~/code/storefront/hum.yaml

Register project configurations via the CLI:

hum project register storefront ./hum.yaml

Use --registry <path> to select another registry. Use --config <path> to bypass the registry and load a project configuration directly.

Project configuration

A version 3 hum.yaml declares:

• runtimes: named process or Compose adapters (process or compose);
• environment_providers: named secret or environment sources (one-password or exec);
• repositories: named checkout roots;
• services: commands, runtimes, working directories, ports, URLs, requirements, readiness constraints, and dependencies;
• tasks: direct-argv one-shot execution units in the dependency graph;
• templates: named service selections;
• logs: rotation, retention, line limits, display redaction, and optional HTTP exporters.

Relative repository paths resolve from the file that declares them. A service cwd resolves from its repository, and env_file resolves from that working directory.

Runtimes and Compose reconciliation

Runtimes isolate execution modes. A Compose runtime maps service names to Compose targets:

runtimes:
  local:
    type: process
  containers:
    type: compose
    project_name: storefront-local
    files: [compose.yaml]
    reconcile: true

When reconcile: true is set, start reapplies running Compose targets if provider-backed environment variables or generated layer files change.

Environment providers

Environment providers read scoped values without leaking them to global shell environments:

environment_providers:
  team-vault:
    type: one-password
  script:
    type: exec
    command: ["./scripts/get-env.sh"]

Services declare provider sources under env_from:

env_from:
  - provider: team-vault
    reference: op://Development/api/environment
    format: dotenv
    optional: true
  - provider: script
    args: ["--json"]
    format: json

• format: dotenv (default) or json (flat JSON object of string values, useful for key names containing characters like / or : such as npm registry auth tokens).
• args: extra arguments passed to exec provider commands.
• schema: optional dotenv file defining exact required key names.
• cache: optional private file path (mode 0600) under .hum/ used when offline.

Service dependencies and readiness

Services and tasks share a dependency graph. Control when a dependency unblocks downstream units:

services:
  web:
    runtime: local
    depends_on: [api]
    depends_on_ready: healthy # started | listening | healthy

Local overrides and environment

Machine-specific values can live in an untracked hum.local.yaml beside the project file. Service environment precedence is:

1. values loaded from .env;
2. service.env values;
3. provider-backed env_from values;
4. service.env_overrides (useful for mapping container endpoints to localhost);
5. the inherited process environment;
6. repeatable CLI overrides such as --env API_URL=http://localhost:3000.

Unknown fields and invalid names, ports, URLs, durations, commands, or references are rejected. Validate a selected configuration or inspect redacted Compose rendering:

hum storefront all-services config validate
hum storefront all-services config compose --format yaml