Configure AgentDbg: Env Vars, YAML, and Precedence

AgentDbg requires no configuration to get started — every setting has a safe default. When you need to customize behavior, you can use environment variables for one-off overrides or YAML config files for persistent, project-wide or user-wide settings. All data stays local; no account or network is required.

How configuration works

AgentDbg accepts settings in two forms:

Environment variables — set in your shell or .env file, effective for a single process invocation.
YAML config files — written once and applied automatically to every run in that scope.

The two YAML locations serve different scopes:

File	Scope
`.agentdbg/config.yaml`	Project — checked in alongside your code, applies to everyone on the project
`~/.agentdbg/config.yaml`	User — personal defaults that apply across all your projects

Precedence order

When the same setting appears in multiple places, AgentDbg uses the value from the highest-priority source and ignores the rest. From highest to lowest:

Function arguments — values passed directly to @trace(...) or traced_run(...)
Environment variables — only when the variable is explicitly set
Project config — .agentdbg/config.yaml in the current working directory
User config — ~/.agentdbg/config.yaml
Defaults — built-in values listed in the table below

Function arguments always win. If you pass max_llm_calls=10 to @trace(...), it overrides the same setting in env vars and both YAML files.

Complete settings reference

Core settings

Env var	YAML key	Default	Description
`AGENTDBG_DATA_DIR`	`data_dir`	`~/.agentdbg`	Base directory for run storage. Runs land in `<data_dir>/runs/<run_id>/`.
`AGENTDBG_REDACT`	`redact`	`1` (on)	Enable redaction. Set to `1`, `true`, or `yes` to enable; any other value disables.
`AGENTDBG_REDACT_KEYS`	`redact_keys`	`api_key,token,authorization,cookie,secret,password`	Comma-separated list of key patterns. Case-insensitive substring match.
`AGENTDBG_MAX_FIELD_BYTES`	`max_field_bytes`	`20000`	Maximum string size in bytes before truncation. Minimum enforced: 100.
`AGENTDBG_LOOP_WINDOW`	`loop_window`	`12`	Number of recent events scanned for repeated patterns. Minimum: 4.
`AGENTDBG_LOOP_REPETITIONS`	`loop_repetitions`	`3`	Consecutive pattern repetitions required to emit a `LOOP_WARNING`. Minimum: 2.
`AGENTDBG_RUN_NAME`	(env only)	(derived)	Override the display name for the current run. Not configurable via YAML.
`AGENTDBG_IMPLICIT_RUN`	(env only)	unset (off)	Set to `1` to auto-create a run on the first `record_*` call, when no `@trace` wraps the code.

Guardrail settings

Guardrails are opt-in. They are all disabled (null) by default and must be set explicitly to take effect.

Env var	YAML key	Default	Description
`AGENTDBG_STOP_ON_LOOP`	`guardrails.stop_on_loop`	`false`	Abort the run when a `LOOP_WARNING` is detected.
`AGENTDBG_STOP_ON_LOOP_MIN_REPETITIONS`	`guardrails.stop_on_loop_min_repetitions`	`3`	Minimum pattern repetition count required to trigger a loop abort. Minimum: 2.
`AGENTDBG_MAX_LLM_CALLS`	`guardrails.max_llm_calls`	`null`	Abort after more than N LLM calls (triggers at N+1).
`AGENTDBG_MAX_TOOL_CALLS`	`guardrails.max_tool_calls`	`null`	Abort after more than N tool calls (triggers at N+1).
`AGENTDBG_MAX_EVENTS`	`guardrails.max_events`	`null`	Abort after more than N total events.
`AGENTDBG_MAX_DURATION_S`	`guardrails.max_duration_s`	`null`	Abort when elapsed run time reaches N seconds.

Full YAML example

The example below shows every available setting. Copy it to .agentdbg/config.yaml in your project root or to ~/.agentdbg/config.yaml as a user-level default, then remove or adjust any line you want to change.

# ~/.agentdbg/config.yaml  or  .agentdbg/config.yaml
data_dir: ~/.agentdbg
redact: true
redact_keys:
  - api_key
  - token
  - authorization
  - cookie
  - secret
  - password
max_field_bytes: 20000
loop_window: 12
loop_repetitions: 3
guardrails:
  stop_on_loop: false
  stop_on_loop_min_repetitions: 3
  max_llm_calls: null
  max_tool_calls: null
  max_events: null
  max_duration_s: null

null in YAML means the guardrail is disabled. Remove the key entirely or set it to a number to enable the limit.

Safe-by-default behavior

AgentDbg ships with two design choices that protect you without any configuration:

Redaction is on by default. Common secret-bearing keys (api_key, token, authorization, cookie, secret, password) are scrubbed from trace data before it is written to disk. You never accidentally persist an API key.
Storage is local by default. Traces land in ~/.agentdbg/ on your own machine. No data is sent to any external service.

Override only what you need. See Redact Secrets from Agent Traces for details on controlling what gets scrubbed, and Local Trace Storage for details on where traces are written and how to move them.

Get Started

SDK

Integrations

Configuration

Reference

Configure AgentDbg: Env Vars, YAML, and Precedence

How configuration works

Precedence order

Complete settings reference

Core settings

Guardrail settings

Full YAML example

Safe-by-default behavior

​How configuration works

​Precedence order

​Complete settings reference

​Core settings

​Guardrail settings

​Full YAML example

​Safe-by-default behavior

How configuration works

Precedence order

Complete settings reference

Core settings

Guardrail settings

Full YAML example

Safe-by-default behavior