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.