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

# Redact Secrets from Agent Traces Automatically

> AgentDbg scrubs values for sensitive keys before writing any trace data to disk, keeping API keys and tokens out of your local trace files by default.

AgentDbg applies redaction to every trace it writes. Before any event data touches disk, AgentDbg walks the payload and replaces values whose keys match known sensitive patterns with the placeholder `__REDACTED__`. This means that even if your agent passes API keys, authorization headers, or passwords through its tool calls or LLM inputs, those values do not end up in your local trace files.

## What redaction does

When AgentDbg records an event, it serializes the payload — which may include nested dicts and lists from LLM inputs, tool arguments, and state snapshots. Before writing, it walks the structure and applies two protections:

* **Key-based redaction:** if a dict key contains any of the configured patterns as a case-insensitive substring, the value is replaced with `__REDACTED__`. The key itself is kept so you can still see which field was sensitive.
* **Size-based truncation:** strings longer than `AGENTDBG_MAX_FIELD_BYTES` bytes (UTF-8) are cut at the limit and suffixed with `__TRUNCATED__`.

Both rules are applied recursively into nested dicts and lists, up to a depth of 10. At depth 10, any remaining value is replaced with `__TRUNCATED__` regardless of size.

## Default behavior

Redaction is **on by default**. You do not need to configure anything to get it.

The default set of redacted key patterns is:

```
api_key, token, authorization, cookie, secret, password
```

Matching is case-insensitive and uses substring comparison. A dict key of `auth_token` matches `token`; `API_KEY` matches `api_key`; `X-Authorization` matches `authorization`.

The default truncation limit is **20,000 bytes**. Strings longer than that are cut and marked `__TRUNCATED__`.

## Configure redaction

<Tabs>
  <Tab title="Env vars">
    ```bash theme={null}
    # Keep redaction on (default)
    export AGENTDBG_REDACT=1

    # Replace the full list of key patterns
    export AGENTDBG_REDACT_KEYS="api_key,token,authorization,cookie,secret,password"

    # Lower the truncation limit
    export AGENTDBG_MAX_FIELD_BYTES=10000
    ```
  </Tab>

  <Tab title="YAML">
    ```yaml theme={null}
    # .agentdbg/config.yaml  or  ~/.agentdbg/config.yaml
    redact: true
    redact_keys:
      - api_key
      - token
      - authorization
      - cookie
      - secret
      - password
    max_field_bytes: 10000
    ```
  </Tab>
</Tabs>

<Info>
  `AGENTDBG_REDACT` accepts `1`, `true`, or `yes` to enable redaction. Any other value disables it.
</Info>

## Add custom redaction keys

To redact additional fields, replace the `AGENTDBG_REDACT_KEYS` list with your full desired set. The list is not additive — if you set it, it replaces the defaults. Include the default patterns you still want to keep.

<Tabs>
  <Tab title="Env vars">
    ```bash theme={null}
    # Adds "session_id" and "client_secret" alongside the defaults
    export AGENTDBG_REDACT_KEYS="api_key,token,authorization,cookie,secret,password,session_id,client_secret"
    ```
  </Tab>

  <Tab title="YAML">
    ```yaml theme={null}
    redact_keys:
      - api_key
      - token
      - authorization
      - cookie
      - secret
      - password
      - session_id
      - client_secret
    ```
  </Tab>
</Tabs>

## Disable redaction for local debugging

If you need to inspect raw payloads during a debugging session, you can turn redaction off entirely.

<Tabs>
  <Tab title="Env vars">
    ```bash theme={null}
    export AGENTDBG_REDACT=0
    ```
  </Tab>

  <Tab title="YAML">
    ```yaml theme={null}
    redact: false
    ```
  </Tab>
</Tabs>

<Warning>
  Disabling redaction means **every value in every payload is written to disk exactly as recorded**, including API keys, tokens, authorization headers, and passwords. Only disable redaction when you are debugging locally and the trace files will not be shared, committed, or left on a shared machine.
</Warning>

## Redaction reference

| Env var                    | YAML key          | Default                                              | Description                                                       |
| -------------------------- | ----------------- | ---------------------------------------------------- | ----------------------------------------------------------------- |
| `AGENTDBG_REDACT`          | `redact`          | `1` (on)                                             | Enable or disable redaction globally.                             |
| `AGENTDBG_REDACT_KEYS`     | `redact_keys`     | `api_key,token,authorization,cookie,secret,password` | Comma-separated list of key patterns. Replaces defaults when set. |
| `AGENTDBG_MAX_FIELD_BYTES` | `max_field_bytes` | `20000`                                              | Truncation limit in bytes. Minimum enforced value: 100.           |

<Tip>
  For a full list of all AgentDbg settings in one place, see [Configuration overview](/docs/configuration/overview).
</Tip>