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

# Privacy and Redaction

> Configure redaction layers, image externalization, telemetry, and checkpoint commit signing.

Use this page to configure privacy-related behavior for a repository or for your local machine.

By default, Entire redacts API keys, access tokens, credentialed URLs, database connection strings, and private keys before it writes checkpoint metadata. Secret scanning remains active, but you can choose which pattern scanner Entire uses.

For the threat model, the full list of redaction layers, and what each layer does and does not cover, see [Security & Privacy](/security).

## Start Here If

Use this page to:

* choose secret scanner engines
* add PII or custom redaction rules
* turn on the OpenAI Privacy Filter
* move inline images out of transcripts
* opt in or out of anonymous CLI analytics
* change checkpoint commit signing

## Settings Reference

Every key below lives under `.entire/settings.json` (shared with the team) or `.entire/settings.local.json` (yours alone), except where noted.

| Setting path | Type | Default | Effect |
| - | - | - | - |
| `redaction.betterleaks.enabled` | boolean | `true` | Run Betterleaks for secret pattern matching. **Project settings only** |
| `redaction.goredact.enabled` | boolean | `false` | Run goredact for secret pattern matching. **Project settings only** |
| `redaction.pii.enabled` | boolean | `false` | Turn on [PII redaction](#pii-redaction) |
| `redaction.pii.email` | boolean | `true` when PII is on | Redact email addresses |
| `redaction.pii.phone` | boolean | `true` when PII is on | Redact phone numbers |
| `redaction.pii.address` | boolean | `false` | Redact US street addresses |
| `redaction.pii.custom_patterns` | object | `{}` | Label-to-regex map producing `[REDACTED_<LABEL>]` tokens |
| `redaction.custom_redactions` | object | `{}` | Label-to-regex map producing the bare `REDACTED` token |
| `redaction.externalize_images` | boolean | `false` | Lift inline base64 images into the checkpoint's `assets/` store |
| `redaction.openai_privacy_filter.enabled` | boolean | `false` | Run [OPF](#openai-privacy-filter) at push time |
| `redaction.openai_privacy_filter.categories` | object | `{}` | Which OPF categories to detect. At least one is required when OPF is enabled |
| `redaction.openai_privacy_filter.timeout_seconds` | number | `30` | Per-invocation timeout for the `opf` process |
| `redaction.openai_privacy_filter.prompt_default` | string | `"ask"` | `ask`, `never`, or `always` |
| `redaction.openai_privacy_filter.command` | string | `"opf"` | Path to the `opf` binary. **Read only from an untracked `.entire/settings.local.json`** |
| `telemetry` | boolean | `null` | Anonymous CLI analytics |
| `sign_checkpoint_commits` | boolean | `true` | Sign checkpoint commits with your existing Git key |

## Secret Scanner Engines

Layer 2 of Entire's redaction pipeline can run Betterleaks, goredact, or both. Betterleaks runs by default and covers several hundred known secret formats. goredact is off by default and checks a smaller set of provider and contextual token shapes with structural validators such as token length or checksums.

> [!NOTE]
>
> CLI 0.10.2 uses Betterleaks and does not support scanner selection. `v0.10.3-nightly.202608210613.680d64782` first exposes the settings below.

Configure scanner selection in the committed project settings file:

```json .entire/settings.json theme={null}
{
  "redaction": {
    "betterleaks": {
      "enabled": true
    },
    "goredact": {
      "enabled": false
    }
  }
}
```

Entire reads these keys only from `.entire/settings.json`. It ignores them in `.entire/settings.local.json` and logs a warning because scanner selection affects the checkpoint content shared through the repository.

> [!WARNING]
>
> Keep at least one scanner enabled. Entire refuses to load settings when both `redaction.betterleaks.enabled` and `redaction.goredact.enabled` are `false`.

If goredact is the only active scanner and it fails during a scan, Entire stops the checkpoint write. When both scanners run, Entire can complete the write with Betterleaks coverage if goredact fails. See [Redaction Layers](/security#redaction-layers) for the complete pipeline.

## PII Redaction

PII redaction is disabled by default. Enable it when checkpoint metadata may include personal information such as email addresses, phone numbers, or addresses.

**Project Settings**

Use project settings when PII redaction should apply to everyone working in the repository.

```json .entire/settings.json theme={null}
{
  "redaction": {
    "pii": {
      "enabled": true,
      "email": true,
      "phone": true,
      "address": false
    }
  }
}
```

**Local Settings**

Use local settings when PII redaction should apply only to your machine.

```json .entire/settings.local.json theme={null}
{
  "redaction": {
    "pii": {
      "enabled": true
    }
  }
}
```

**Custom Patterns**

Each label becomes part of the replacement token, uppercased. The pattern below produces `[REDACTED_EMPLOYEE_ID]`.

```json .entire/settings.json theme={null}
{
  "redaction": {
    "pii": {
      "enabled": true,
      "custom_patterns": {
        "employee_id": "EMP-\\d{6}"
      }
    }
  }
}
```

A pattern that reveals an internal ID format is itself sensitive. Put that one in `.entire/settings.local.json`, which stays out of Git.

See [PII redaction](/security#pii-redaction-optional) for categories, defaults, and limitations.

## User-Defined Redaction

User-defined redaction lets you redact project-specific strings that Entire's built-in secret detection may not catch. Patterns use Go RE2 syntax, so lookarounds and backreferences are unavailable.

**Inline Rules**

Use inline rules for a small number of patterns.

```json .entire/settings.json theme={null}
{
  "redaction": {
    "custom_redactions": {
      "acme_token": "ACME_TOKEN_[A-Za-z0-9]{20,}",
      "internal_id": "INTERNAL_[a-z]{6}_[0-9]{4}"
    }
  }
}
```

Put shared rules in `.entire/settings.json`. Put private rules in `.entire/settings.local.json`. Entries merge per key, so a local rule can override one shared key and leave the rest alone.

**Rule Packs**

Use rule packs for larger reusable sets of redaction rules. Shared packs go in `.entire/redactors/`. Personal packs go in `.entire/redactors/local/`, which `entire enable` keeps gitignored.

```yaml .entire/redactors/acme-internal.yaml theme={null}
name: acme-internal
version: 1.0.0
description: Internal ACME service tokens
rules:
  - id: acme-token
    description: Long-lived ACME service tokens
    regex: 'ACME_TOKEN_[A-Za-z0-9]{20,}'
    samples:
      - { input: "key=ACME_TOKEN_abc123def456ghi789jkl", redacted: true }
      - { input: "ACME_TOKEN_short", redacted: false }
  - id: acme-session
    regex: 'asess_[a-f0-9]{32}'
```

`name` has to match the filename stem. Every pack also needs a `version` and at least one rule carrying an `id` and a `regex`. Entire reads the `.yaml`, `.yml`, and `.json` extensions.

Rules take effect on the next CLI or hook invocation. See [User-defined redaction](/security#user-defined-redaction) for rule pack behavior, sample self-tests, and validation details.

## OpenAI Privacy Filter

The OpenAI Privacy Filter is an optional layer that runs a local token-classification model over checkpoints at push time, catching names and other personal data that regex layers miss. It is off by default.

> [!WARNING]
>
> OPF runs on the `entire/checkpoints/v1` branch backend. Repositories on the ref-based backend, which is the default for repositories enabled with CLI 0.10.0 or later, push without the OPF pass. Check `checkpoints.primary.type` in `.entire/settings.json` before enabling OPF, and see [Session Storage](/guides/checkpoints/checkpoint-storage) to change backends.

### Install `opf`

```bash theme={null}
pip install opf
```

Confirm the binary resolves before you enable the filter, because a missing `opf` aborts your pushes:

```bash theme={null}
opf --help
```

### Enable It

OPF needs at least one category. Enabling the filter with no category selected aborts the push with a configuration error rather than tagging commits as scanned.

```json .entire/settings.json theme={null}
{
  "redaction": {
    "openai_privacy_filter": {
      "enabled": true,
      "categories": {
        "private_person": true
      },
      "timeout_seconds": 30,
      "prompt_default": "ask"
    }
  }
}
```

### Categories

Set a category to `true` to detect it. Entire rejects unknown category names when it loads settings, so a typo surfaces immediately instead of silently disabling a category.

| Category | Replacement token | Detects |
| - | - | - |
| `private_person` | `[REDACTED_PERSON]` | Person names |
| `private_email` | `[REDACTED_EMAIL]` | Email addresses |
| `private_phone` | `[REDACTED_PHONE]` | Phone numbers |
| `private_address` | `[REDACTED_ADDRESS]` | Street addresses |
| `private_url` | `[REDACTED_URL]` | URLs that may identify a person or account |
| `private_date` | `[REDACTED_DATE]` | Dates such as a date of birth |
| `account_number` | `[REDACTED_ACCOUNT_NUMBER]` | Account, card, and SSN-shaped numbers |
| `secret` | `REDACTED` | Generic credential-shaped values |

### Control the Pre-Push Prompt

`prompt_default` decides whether the pre-push hook asks before running OPF.

| Value | Behavior |
| - | - |
| `"ask"` | Prompt on an interactive push. This is the default |
| `"always"` | Run without asking |
| `"never"` | Skip OPF, and push content redacted by the regex layers only |

Choosing **Always** at the prompt writes `prompt_default: "always"` into `.entire/settings.local.json` for you.

### Override for a Single Push

`ENTIRE_OPF` beats both the setting and the prompt, for that push only.

```bash theme={null}
ENTIRE_OPF=no git push
```

Use `ENTIRE_OPF=no` when a CI runner pushes without `opf` installed. Use `ENTIRE_OPF=yes` to run OPF without a prompt.

### Push Caps

Two environment variables bound how much work one push hands to the model. Both accept a number or `unlimited`.

| Variable | Default | Guards against |
| - | - | - |
| `ENTIRE_OPF_BOOTSTRAP_LIMIT` | `100` commits | A first push to a remote with no checkpoint history rewriting hours of commits |
| `ENTIRE_OPF_BATCH_LIMIT` | `2097152` bytes (2 MiB) | A single commit carrying a very large pasted transcript |

```bash theme={null}
ENTIRE_OPF_BATCH_LIMIT=10485760 git push
```

### The `command` Setting

`command` points at a specific `opf` binary. Entire reads it only from `.entire/settings.local.json`, and only when that file is untracked, because the value becomes a process Entire executes during `git push`. Entire logs a rejected `command` and falls back to `$PATH`.

```json .entire/settings.local.json theme={null}
{
  "redaction": {
    "openai_privacy_filter": {
      "command": "/opt/homebrew/bin/opf"
    }
  }
}
```

See [The `command` setting is local-only](/security#openai-privacy-filter-optional) for why this restriction exists.

## Externalized Images

`redaction.externalize_images` moves inline base64 images out of transcript files and into the checkpoint's `assets/` store, replacing each with a short `entire-asset:assets/...` placeholder. It is off by default.

```json .entire/settings.json theme={null}
{
  "redaction": {
    "externalize_images": true
  }
}
```

`ENTIRE_EXTERNALIZE_IMAGES=1` turns it on for one invocation without editing settings.

Turning this on keeps large binary blobs out of `full.jsonl` and `transcript.jsonl`, which makes those files cheaper to read and diff. Restore re-injects images byte-exactly whether or not the flag is on.

> [!WARNING]
>
> This setting changes where Entire stores image bytes, not whether any layer scans them. No redaction layer reads image content in either arrangement, so an image containing a credential or customer data reaches the remote intact. See [Externalized images](/security#externalized-images).

## Telemetry

Telemetry controls anonymous CLI usage analytics. It does not send prompts, transcripts, source code, file paths, repository names, or flag values.

**Settings File**

To opt out in this repository, set:

```json .entire/settings.json theme={null}
{
  "telemetry": false
}
```

Use `.entire/settings.local.json` instead when the telemetry preference should apply only to your machine.

**Environment Variable**

To opt out for a single command or shell environment, set:

```bash theme={null}
ENTIRE_TELEMETRY_OPTOUT=1 entire status
```

See [Telemetry and analytics](/security#telemetry-and-analytics) for what is and is not captured.

## Checkpoint Commit Signing

Checkpoint commits are signed by default when your Git signing setup is available.

To disable signing for the repository, set:

```json .entire/settings.json theme={null}
{
  "sign_checkpoint_commits": false
}
```

Use `.entire/settings.local.json` instead when the signing preference should apply only to your machine.

See [Checkpoint commit signing](/security#checkpoint-commit-signing) for requirements and best-effort behavior.

## Verify Privacy Settings

After changing privacy settings, run:

```bash theme={null}
entire status --detailed
```

For redaction changes, run a normal Entire workflow after updating settings. Entire skips an invalid regex or a malformed rule pack and writes the reason to `.entire/logs/entire.log` instead of stopping the CLI.

To confirm OPF ran, push and then check the checkpoint commit for its trailer:

```bash theme={null}
git log -1 --format=%B entire/checkpoints/v1 | grep Entire-OPF-Applied
```