> ## Documentation Index
> Fetch the complete documentation index at: https://refinehq.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Info>
  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.
</Info>

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

```yaml theme={null}
# ~/.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
```

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

## 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](/docs/configuration/redaction) for details on controlling what gets scrubbed, and [Local Trace Storage](/docs/configuration/storage) for details on where traces are written and how to move them.