Configuration - AgentGuardian

How agent-guardian resolves every setting at scan time. The schema is sourced from src/agent_guardian/config.py; every key documented here is a field on a real Pydantic model with extra="forbid" — typos raise at load time.

When to use a config file

The CLI works out of the box with zero config. Reach for a YAML file when:

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)

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

A missing config file is a no-op: the CLI uses defaults so a fresh install works. Missing sections inside a file also fall back to defaults — a half-populated file is fine.

Config file discovery

load_config(path=None) walks this chain:

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

First hit wins. Stop the search by setting --config to a real path or by deleting the higher-priority candidates.

Full schema

The Pydantic shape, exactly as the loader enforces it:

swarm:
  commander_model: claude-haiku-4-5     # default
  attacker_model: gpt-4o-mini           # default
  evaluator_model: gpt-4o-mini          # default
  max_parallel_agents: 11               # default; clamped to 1..=11
  budget:
    wall_seconds: 900                   # default (15 min); must be >= 1
    max_total_tokens: 2000000           # default (2M); 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: true                      # default
  sign_evidence: true                   # default
  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

Every section has sensible defaults. The shortest valid config file is an empty document:

# .agentguardian.yaml — every field defaults

`swarm`

LLM identifiers and budget for one scan.

Key	Default	Notes
`commander_model`	`claude-haiku-4-5`	Commander LLM. CLI override: `--commander-model` or `--model`.
`attacker_model`	`gpt-4o-mini`	Attacker LLM. CLI override: `--attacker-model` or `--model`.
`evaluator_model`	`gpt-4o-mini`	Judge / evaluator LLM. CLI override: `--evaluator-model` or `--model`.
`max_parallel_agents`	`11`	Cap on concurrent specialist agents. Range `1..=11`.
`budget.wall_seconds`	`900`	Hard wall-clock cap. Range `>= 1`.
`budget.max_total_tokens`	`2000000`	Token budget across all roles. Range `>= 1`.

The runtime USD cap is a CLI / SDK concern only (--budget-usd or SwarmConfig.usd_cap) — it’s not in the config schema today.

`target`

Default target shape. The CLI’s four target modes (TARGET positional / --system-prompt / --endpoint / --framework) override this section.

Key	Default	Notes
`mode`	`prompt`	One of `prompt`, `code`, `http`, `framework`.
`path`	`null`	For `mode: prompt` / `code`.
`endpoint`	`null`	For `mode: http`.
`framework`	`null`	For `mode: framework` — the framework kind.
`tier`	`null`	Optional tier override. One of `T1`, `T2`, `T3`, `T4`.

`output`

Default report shape.

Key	Default	Notes
`formats`	`["json"]`	List of formats to emit. Each must be one of `json`, `sarif`, `junit`, `md`, `pdf`.
`redact_pii`	`true`	Run findings through `PiiRedactor` before emit.
`sign_evidence`	`true`	Attach HMAC-SHA256 + Ed25519 signatures to JSON reports.
`output_dir`	`null`	Where reports land. `null` = alongside the scan dir.

`server`

Defaults for the serve command.

Key	Default	Notes
`host`	`127.0.0.1`	Bind host. Loopback by default — see serve for the off-loopback rules.
`port`	`7474`	Bind port. Range `1..=65535`.

`telemetry`

Key	Default	Notes
`enabled`	`false`	Disabled until you opt in via `agent-guardian telemetry essential` / `telemetry extended`.

Environment variables

Settings the CLI reads from the environment.

Provider API keys

The CLI accepts both a namespaced key and the provider’s conventional env var. The namespaced key wins.

Provider	Namespaced (preferred)	Conventional fallback
OpenAI	`AGENT_GUARDIAN_OPENAI_API_KEY`	`OPENAI_API_KEY`
Anthropic	`AGENT_GUARDIAN_ANTHROPIC_API_KEY`	`ANTHROPIC_API_KEY`
Gemini (AI Studio)	`AGENT_GUARDIAN_GEMINI_API_KEY`	`GEMINI_API_KEY`, then `GOOGLE_API_KEY`
AWS Bedrock	—	Standard AWS chain: `AWS_REGION` / `AWS_DEFAULT_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`, `AWS_PROFILE`, or IAM role. No `--api-key` is consulted.
Ollama	—	Local — no auth.

agent-guardian doctor lists which keys it found without sending a request. doctor --check-connectivity issues one tiny validation call per provider.

CLI behaviour

Variable	Default	Effect
`AGENT_GUARDIAN_HOME`	`~/.agentguardian`	Root for state, scans, signed reports, leaderboards.
`AGENT_GUARDIAN_DASHBOARD_URL`	`http://127.0.0.1:7474`	Base URL for the live-dashboard links the scanner prints. Trailing slashes are stripped.
`AGENT_GUARDIAN_DASHBOARD_TOKEN`	unset	Dashboard auth token. Required for non-loopback `serve` binds unless `--insecure-no-auth` is passed. Same value clients must present via the `X-Dashboard-Token` header (or Bearer auth).
`AGENT_GUARDIAN_DASHBOARD_INGEST_TOKEN`	unset	Enables the telemetry-ingest WRITE endpoint off-loopback.
`AGENT_GUARDIAN_DASHBOARD_ALLOW_PUBLIC_INGEST`	unset	When `1`, allow off-loopback telemetry writes without a token.
`AGENT_GUARDIAN_DISABLE_URL_EMISSION`	unset	When `1`, suppress the two `▸ Scan …` URL lines on stdout. Same as `--no-publish`.
`AGENT_GUARDIAN_DISABLE_AUTO_SERVE`	unset	When `1`, disable the auto-spawn dashboard for `scan` runs. Same as `--no-serve`.
`AGENT_GUARDIAN_SIGNING_SECRET`	unset (uses public `DEFAULT_SIGNING_SECRET`)	HMAC secret for signed reports. The public default is never accepted on `verify` — verification requires an explicit anchor.
`AGENT_GUARDIAN_LOG_LEVEL`	`INFO`	Set to `DEBUG` for the full review trace.

Observability (OpenTelemetry)

Variable	Default	Effect
`OTEL_EXPORTER_OTLP_ENDPOINT`	unset	OTLP-HTTP endpoint for GenAI spans (e.g. `http://localhost:4318/v1/traces`). Same as `--otel-endpoint`.
`OTEL_SEMCONV_STABILITY_OPT_IN`	unset	Set to opt in to stable / GenAI semconv flavours. `doctor` reports the current value.

Auto-loaded `.env`

When python-dotenv is installed (it’s in the dev extra), the CLI loads ./.env and ./.env.local from the current working directory at startup. Existing shell exports always win — .env never overrides them. Project-local only: .env files in $HOME or arbitrary ancestor directories are not loaded, to avoid leaking keys between projects.

Runnable example

A complete .agentguardian.yaml for a small team:

# .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

Validate it loads cleanly:

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

Expected output: a Config(...) repr with the values above (and any unset key showing its default). A typo or wrong type raises a Pydantic ValidationError instead.

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.

Documentation Index

​When to use a config file

​Precedence (highest wins)

​Config file discovery

​Full schema

​swarm

​target

​output

​server

​telemetry

​Environment variables

​Provider API keys

​CLI behaviour

​Observability (OpenTelemetry)

​Auto-loaded .env

​Runnable example

​How to interpret the result

​Next step