Skip to main content

Configuration Reference

The core execution engine of azuma nori relies on a centralized JSON configuration (config.json). The Standalone Client manages this file for you automatically in your .nori directory, but understanding its structure is crucial for power-users and future CI/CD integrations.

Core Properties​

A standard config.json is composed of several root configurations:

1. ModelConfig​

Defines the LLM provider, target model, and authorization mechanism used for inference.

  • Provider: The AI provider (e.g., Anthropic, OpenAI, Google, or local executables).
  • ModelId: The specific model variant (e.g., claude-sonnet-5). Model IDs are illustrative — use the current ID from your provider. Antigravity's model IDs carry an effort tier (gemini-3.8-flash-medium, gemini-4-argon-high); a bare ID runs at the model's default tier. Run agy models to list the valid IDs. In the desktop app the Model ID field suggests the identifiers nori knows for the provider you picked — while still accepting anything you type, so a model newer than the list is never blocked. GitHub Copilot is the one provider where the ID is mandatory: the tools it offers vary by model, so a run will not start without one or with auto, which hands the choice of model back to Copilot; the field says so as soon as you enter it. A paid Copilot plan is required because Copilot Free rejects every explicit ID.
  • ConnectionType: Dictates how the model is reached: "DirectAPI" (calls the provider's cloud API with an API key) or "CLI" (proxies through a pre-authorized local agent CLI like Claude/Antigravity CLI). Some providers accept only one value — Antigravity and GitHub Copilot are CLI-only, Gemini and Ollama are Direct API-only. See LLM Models & Usage.
  • CliBinaryPath: Explicit path to the agent CLI executable. When empty, resolves from PATH. On Windows, nori re-reads the persistent system and user PATH at startup, so a CLI installed after you signed in is found on the next restart without signing out. Set this only if the executable still isn't located.
  • Endpoint: Overrides the default provider API URL. Useful for routing requests through internal corporate proxies or targeting an on-premise Private Azure OpenAI deployment.
  • ApiKey: The authentication token.
    • Security Best Practice: Use the ${ENV_VAR} syntax (e.g., ${OPENAI_API_KEY}) to resolve keys from the runtime environment. This guarantees your secret keys are never hardcoded inside the config.json text file.
  • TestDirectory: Specific to the TestConnection execution scope, this dictates where a safe diagnostic probe is executed to verify connectivity.

2. AnalysisConfig​

Controls the behaviour and resource utilization of the policy evaluation engine.

  • Model: Optional per-phase override of type ModelOverrideConfig (see below). Unset fields fall back to the top-level ModelConfig.
  • Depth: Controls the thoroughness of the evaluation (Light, Medium, Extreme).
  • Parallelism: Limits the number of concurrent sub-agents the orchestrator will spawn, ensuring you don't exhaust local CPU threads or hit API rate limits.
  • MaxBudgetUsd: Implements a hard cap on API spend per run. The engine will halt if projected token costs exceed this threshold.
  • CompressWikiContext: Strips filler prose from the local index content before it is injected into the agent prompts, without sacrificing factual integrity. The saving depends on how much prose the source index holds — tables, paths and code barely compress — so each run measures its own, in characters, and reports it in the run log and beside the Compress source index context toggle in the desktop app.
  • SkipExisting: A resumability flag. When enabled, the engine scans the .nori cache for previously completed findings and only evaluates outstanding controls, saving time and money on interrupted runs.
  • InjectRecordedScope (default true): Hands each control the risk classification you confirmed in the guided triage, so controls assess against your recorded determination instead of each deciding for themselves whether the regulation reaches your project. A control whose reading of your code contradicts that determination is held back and reported rather than quietly ruled out of scope. Set false to withhold the classification from the analysis — controls then fall back to deciding scope individually, and the held-control outcome cannot arise. Only applies where the selected policy defines a classification; otherwise it has no effect.

3. WikiConfig​

Controls the generation of the source index — the local codebase indices (called the "Wiki" in versions before 1.26.0, hence the name of this block).

  • Model: Optional override of type ModelOverrideConfig for building the source index (allows selecting a cheaper model for mechanical scanning).
  • Concise: A boolean flag. When true, instructs nori to generate concise, fact-dense source index pages to cap verbosity and save token costs in downstream evaluations.
  • Parallelism: Number of concurrent source index tasks.
  • SkipExisting: Resumability flag to skip already generated source index pages.
  • MaxBudgetUsd: Spend cap per source index agent call (Claude CLI only).

4. DocIndexConfig​

Controls the generation of the document index — the summaries of your document evidence.

  • Model: Optional override of type ModelOverrideConfig for the document index (e.g., pointing to a Claude CLI model for visual parsing of PDFs and diagrams).
  • Parallelism: Number of concurrent document index tasks.
  • MaxExtractChars: Limits the characters of extracted text passed to text-only summaries (defaults to 120_000 to prevent runaway prompt size).
  • MaxSourceBytes: Size guard (e.g. 52_428_800 bytes) above which files are marked Unsupported to protect against zip-bombs or pathologically large files.
  • MaxBudgetUsd: Spend cap per summarizer agent call (Claude CLI only).

Model Overrides​

Where Model overrides are configured (for Analysis, Wiki, or DocIndex blocks), they use the ModelOverrideConfig structure. Leave fields empty to fall back to the top-level project model configuration:

  • Provider: Overrides provider type (e.g. Google).
  • ModelId: Overrides model variant (e.g. gemini-2.5-flash).
  • Endpoint: Custom endpoint URL override.
  • ConnectionType: Overrides connection type (DirectAPI vs CLI).

Local Overrides​

Like all standard .NET Core applications, nori supports a configuration hierarchy. If you create an appsettings.local.json file in the execution directory, those values will transparently override the matching properties in config.json. This is ideal for testing configuration tweaks locally without modifying the shared project configuration.