Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Configuration

Status: proposed — consolidated 2026-09-01 from material already designed in 040-cli.md, 020-provider-adapters.md, and 002-data-model.md. No new design decisions were made here; this document is the single place to read the whole configuration surface instead of following links across three docs.

Scope

Consolidated design of configuration for both roles after ADR-012 — the orchestrator host (config.toml) and each worker host (worker.toml, providers.toml, worker token file) — under the per-host platform data dir, plus environment-variable and CLI-flag precedence.

Platform Data Dir

Every config and credential file lives under one per-host directory, resolved via the directories crate (ADR-011):

  • macOS: ~/Library/Application Support/pam/
  • Linux: ~/.local/share/pam/
RoleFiles it holds
Central orchestratorconfig.toml, token
Workerworker.toml, worker-token, providers.toml, runs/

Orchestrator Config (config.toml)

[server]
bind = "0.0.0.0"
port = 7898

[database]
url = "postgresql://pam@localhost:5432/pam"

[providers]
catalog_path = "<platform data dir>/providers.toml"

[retention]
events_days = 30
  • [server] — bind address and port for the HTTP/WS listener.
  • [database] — PostgreSQL DSN; no default, required to serve.
  • [providers] — path to the provider catalog TOML (schema owned by 020-provider-adapters.md).
  • [retention] — events_days controls how long events-table rows are kept before a best-effort purge at orchestrator startup (default 30 days; see 002-data-model.md § Data Retention).

Worker Config (worker.toml)

[worker]
name = "dev-mac"
api_url = "https://pam.example.internal:7898"

[providers]
catalog_path = "<platform data dir>/providers.toml"
  • [worker] — the host’s registered name and the central orchestrator’s base URL it dials out to (outbound-only uplink; no inbound listener).
  • [providers] — same catalog-path key as the orchestrator side; each worker host keeps its own providers.toml copy.

Authentication is a separate file, not a config key: the worker token minted by pam host add is stored in worker-token (or PAM_WORKER_TOKEN) — see 061-security.md § Token Lifecycle.

Provider Catalog (providers.toml)

Schema, per-provider fields, and the completion-signal hook config are owned by 020-provider-adapters.md § Provider Catalog — not duplicated here. Default path: <platform data dir>/providers.toml, overridable via the catalog_path key above.

Gateway Config ([gateway] section, optional)

A proxy/gateway base URL and API key, read from the same config.toml. The gateway itself is one centrally-shared, network-reachable instance (e.g. an internal liteLLM deployment), not a local process per host (ADR-013):

[gateway]
url = "https://gateway.internal:8080"
api_key = "sk-gateway-key"

pam only injects these into the provider CLI’s environment (ANTHROPIC_BASE_URL etc.) at spawn time — see 020-provider-adapters.md § Gateway Operations Scope for what is explicitly out of scope (gateway lifecycle, health checks, routing).

Environment Variables

Environment variables are the third-priority source for every key below — below a CLI flag and below a config file value, above the built-in default. See § Precedence Order below for the full four-source chain.

Gateway settings use PAM_GATEWAY_URL / PAM_GATEWAY_API_KEY and are listed separately in 020-provider-adapters.md § Configuration Source.

Precedence Order

All settings now resolve config-file-first — one consistent rule across both groups (resolves OQ-16, which tracked this asymmetry until now):

Core CLI settings (PAM_API_URL, PAM_TOKEN, PAM_WORKER_TOKEN, PAM_BIND, PAM_PORT, PAM_DATABASE_URL, PAM_CONFIG, PAM_WORKER_CONFIG):

  1. CLI flag (highest — e.g. --api-url, --config; an explicit, one-shot value typed at invocation time)
  2. Config file value
  3. Environment variable
  4. Built-in default (where one exists)

Gateway settings ([gateway] section) — no CLI flag exists for these, so the chain is:

  1. Config file value (highest)
  2. PAM_GATEWAY_URL / PAM_GATEWAY_API_KEY
  3. Provider-specific env vars (ANTHROPIC_BASE_URL etc.), lowest-priority fallback

Rationale: a config-managed deployment (e.g. Ansible/Terraform writing one config.toml) gets one predictable source of truth, and a value left over in a shell session can no longer silently outrank a value someone just changed in the file.

Open Questions

  • OQ-16 (RESOLVED 2026-09-01): resolved — all settings now resolve config-file-first (see § Precedence Order above). Full resolution recorded in 071-risks-and-open-questions.md.