Configuration

File format

Settings live in JSONC: JSON with comments and trailing commas. A published JSON Schema gives editor autocomplete and inline validation in VS Code, Cursor, Zed, JetBrains, and anything else that respects $schema.

Locations

Two files, merged project-over-user (project values win field by field):

1. ~/.config/harnery/config.jsonc: user-global base for every project on the machine (honors XDG_CONFIG_HOME, falling back to ~/.config)
2. <project-root>/.harnery/config.jsonc: the project file, authoritative

CLI flags and HARNERY_* env vars override both per invocation (each field’s env override is noted in the schema reference). A project that sets only web.port keeps a user-global web.bind; the merge is field-by-field, not whole-object.

Schema

Reference the published JSON Schema at the top of your config:

{
  "$schema": "https://harnery.com/schemas/config.schema.json",

  // ... your settings here
}

VS Code (and most modern editors) read the $schema URL and provide autocomplete + validation as you type.

Example

{
  "$schema": "https://harnery.com/schemas/config.schema.json",

  // Project identity surfaced to peers + in log lines.
  "project_name": "my-project",

  // Coord layer
  "coord": {
    "freshness_seconds": 600,  // how stale a peer heartbeat can get before sweep
    "finalization": {
      "archive_grace_seconds": 600,
      "idle_observe_seconds": 259200,
      "idle_finalize_seconds": 604800,
      "cascade_grace_seconds": 3600,
      "reconcile_interval_seconds": 900
    },
    "run_quality": {
      "mode": "off"  // opt into shadow or report only after local evaluation
    }
  },

  // Repository-local working files
  "artifacts": {
    "default_retention_days": 3
  },

  // Soft storage budgets for manifest-backed operational and debug logs.
  "logs": {
    "storage": {
      "classes": {
        "operational-log": {
          "max_bytes": 134217728,
          "max_age_days": 30
        },
        "debug-log": {
          "max_bytes": 67108864,
          "max_age_days": 7
        }
      },
      "families": {
        "web-performance-log": {
          "max_bytes": 67108864,
          "max_age_days": 14
        }
      }
    }
  },

  // Web UI
  "web": {
    "port": 4276,
    "bind": "127.0.0.1"
  },

  // Backup (restic)
  "backup": {
    "repo": "rclone:gdrive:harnery-backup/my-project",
    "keep_daily": 7,
    "keep_weekly": 4,
    "keep_monthly": 6
  }
}

Log storage values are retention budgets, not write quotas. Harnery keeps accepting valid records when a family is over budget. Use harn logs list to see effective limits and pressure, then preview any cleanup with harn storage maintain before confirming one exact transaction.

See reference / config schema for the full field listing.