Settings & Health API

{
  gatewayUrl: string // e.g. "ws://localhost:18789" (may be empty)
  hasToken: boolean // true if a non-empty gatewayToken is stored
  firstRunDismissedAt: number | null // epoch ms when the first-run UI was dismissed, else null
}

{ "error": "Failed to load settings" }

curl http://localhost:18790/api/settings

{
  gatewayUrl?: string          // must be ws:// or wss:// if non-empty (host unrestricted); '' clears it
  gatewayToken?: string        // '' clears the stored token
  firstRunDismissedAt?: number // epoch ms; only applied when typeof === 'number'
}

{ "ok": true }

{ "error": "JSON body required" }

{ "error": "gatewayUrl must be a ws:// or wss:// URL" }

{ "error": "Failed to save settings" }

# Set the upstream gateway URL and token
curl -X POST http://localhost:18790/api/settings \
  -H 'Content-Type: application/json' \
  -d '{"gatewayUrl":"ws://localhost:18789","gatewayToken":"<token>"}'

# Dismiss-only update — leaves the gateway URL/token untouched
curl -X POST http://localhost:18790/api/settings \
  -H 'Content-Type: application/json' \
  -d '{"firstRunDismissedAt":1750000000000}'

{
  ok: boolean // = fatal.length === 0; the one-field liveness summary
  // ...the full BootReport (startedAt, finishedAt, checks, degraded, fatal, config, resolved)
}

{ "ok": false, "error": "<message>" }

curl http://localhost:18790/api/health

{ "ok": false, "error": "<message>" }

curl -X POST http://localhost:18790/api/health/recheck

interface BootReport {
  startedAt: Date // ISO string in JSON
  finishedAt: Date // ISO string in JSON
  checks: BootCheck[]
  degraded: string[] // check ids that failed but the server still runs
  fatal: string[] // check ids that prevent a working server
  config: BootConfig
  resolved: {
    clawbooHome: string
    dbPath: string
    apiPort: number | null
    stateDir: string
    vaultPresent: boolean
    masterKeyOk: boolean
  }
}

interface BootCheck {
  id: string
  ok: boolean
  message: string // short, user-friendly status
  detail?: string // optional multi-line detail
  durationMs: number
}

interface BootConfig {
  logLevel: string
  budgetPosture: string
  budgetHardCapUsdCents: number | null
  budgetWarnSoftPct: number
  otelEnabledByDefault: boolean
  otelActive: boolean // whether an OTLP endpoint is configured THIS boot
}