Configure AgentDbg: Env Vars, YAML, and Precedence

AgentDbg reads settings from env vars and two YAML config files. Env vars win over project YAML, which wins over user YAML, then built-in defaults.

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:

1. Function arguments — values passed directly to @trace(...) or traced_run(...)
2. Environment variables — only when the variable is explicitly set
3. Project config — .agentdbg/config.yaml in the current working directory
4. User config — ~/.agentdbg/config.yaml
5. 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.