Configuration

​

When to use a config file

• You’re checking the same project into git and want CI runs to be reproducible without sprawling CLI flags.
• You have a team-wide default model / budget you want every developer to pick up.
• You want one project’s settings to live next to its code without polluting ~/.agentguardian/config.yaml.

​

Precedence (highest wins)

1. Explicit CLI flags         (--model, --tier, --budget-usd, …)
2. Environment variables      (AGENT_GUARDIAN_*, plus standard provider keys)
3. YAML config file           (--config, then ./.agentguardian.yaml, then ~/.agentguardian/config.yaml)
4. Built-in defaults          (baked into the Pydantic models)

​

Config file discovery

1. The explicit path passed via --config PATH.
2. ./.agentguardian.yaml in the current working directory.
3. ~/.agentguardian/config.yaml.

​

Full schema

swarm:
  commander_model: claude-haiku-4-5     # default
  attacker_model: gemini-3.5-flash      # default
  evaluator_model: gemini-3.5-flash     # default
  max_parallel_agents: 11               # default; clamped to 1..=11
  budget:
    wall_seconds: null                  # default (uncapped); set an int >= 1 to cap
    max_total_tokens: 10000000          # default (10M); must be >= 1

target:
  mode: prompt                          # default; one of: prompt | code | http | framework
  path: null                            # optional
  endpoint: null                        # optional
  framework: null                       # optional
  tier: null                            # optional override; one of T1 | T2 | T3 | T4

output:
  formats: ["json"]                     # default; list of formats to emit
  redact_pii: false                     # default (opt-in PII redaction)
  sign_evidence: true                   # DEPRECATED (no-op) — see note below
  output_dir: null                      # optional; default is alongside the scan

server:
  host: 127.0.0.1                       # default (loopback)
  port: 7474                            # default; 1..=65535

telemetry:
  enabled: false                        # default; disabled until opt-in

# .agentguardian.yaml — every field defaults

​

swarm

​

target

​

output

As of 1.0: scan-bundle integrity signing keyed by output.sign_evidence is not yet wired. The flag is accepted for forward compatibility so existing operator configs don’t break on upgrade, but setting it has no effect today — agent-guardian emits a DeprecationWarning on config load if the field is present. What is signed today, unconditionally:

• Every scan.json ships with Ed25519 + HMAC-SHA256 signatures, verifiable via agent-guardian verify <scan.json>. This happens regardless of the sign_evidence value.
• Release artifacts (PyPI wheel / sdist, GitHub release tarball) are signed via Sigstore + verified-publisher OIDC in CI.

Bundle-level Sigstore signing — the path the sign_evidence flag was originally intended to gate — is roadmapped for 1.1.0. The flag will gain effect there, or be removed if the implementation lands without needing operator opt-in.

​

server

​

telemetry

​

Environment variables

​

Provider API keys

​

CLI behaviour

​

Observability (OpenTelemetry)

​

Auto-loaded .env

​

Runnable example

# .agentguardian.yaml
swarm:
  commander_model: claude-haiku-4-5
  attacker_model: gpt-4o-mini
  evaluator_model: gpt-4o-mini
  budget:
    wall_seconds: 600
    max_total_tokens: 1500000

target:
  mode: http
  endpoint: https://api.your-agent.com/v1/chat

output:
  formats: ["sarif", "md"]
  redact_pii: true
  # sign_evidence: true  # omitted — DEPRECATED in 1.0 (no-op); see `output` table above

python -c "from agent_guardian.config import load_config; print(load_config())"

​

How to interpret the result

• Extra keys at any level fail — the loader uses extra="forbid". If you see Extra inputs are not permitted, you’ve got a typo or you’re trying to extend the schema (open an issue).
• agent-guardian doctor reports the effective config file path: the line config (cwd): <path> (or <not present>) tells you what the CLI sees right now.
• Provider keys are read at scan time, not load time. Rotating a key doesn’t require restarting the dashboard.

​

Next step

• Pair this with the CLI reference to see which flag overrides which key.
• Read the Python SDK page if you want programmatic access to the same Config model.
• Wire it into a CI job — see GitHub Actions integration.