Configuration

Configuration Reference

Three files control Pretense: .pretense.yaml for settings, .pretenseignore for exclusions, and ~/.pretense/credentials.json for authentication. All are created automatically by pretense init.

proxy mutation secrets audit rules team

Complete default configuration

.pretense.yaml

# .pretense.yaml -- full configuration reference
version: "0.6"

proxy:
  port: 9339
  timeout: 30000

mutation:
  enabled: true
  strategy: djb2
  saltRounds: 4
  languages:
    - typescript
    - javascript
    - python
    - go
    - java
  exclude:
    - "*.test.ts"
    - node_modules
  preserveComments: true
  preserveStrings: true

rules:
  - pattern: "getUserPayment.*"
    action: mutate
    note: "payment functions"
  - pattern: "STRIPE_.*"
    action: block
    note: "Stripe secrets"

secrets:
  patterns: default
  customPatterns: []
  blockOnDetect: true

audit:
  enabled: true
  retentionDays: 90
  export: sqlite
  exportFormat: json

team:
  maxSeats: 100
  plan: pro

Run pretense init to generate this file in your project root. All fields are optional -- defaults are used for any field you omit.

.pretense.yaml .pretenseignore credentials.json Environment overrides

.pretense.yaml schema

The main configuration file. YAML format for readability. Created in your project root by pretense init.

proxy

Controls the local HTTP proxy server that intercepts LLM API traffic.

Field	Type	Default	Description
`proxy.port`	number	`9339`	Port the Pretense proxy listens on. Change this if 9339 conflicts with another service. Example: `9339`
`proxy.timeout`	number	`30000`	Maximum milliseconds to wait for an upstream LLM API response before returning a 504. Increase for large completions. Example: `30000`

mutation

Controls which files are scanned, which languages are supported, and what token types are mutated.

Field	Type	Default	Description
`mutation.languages`	string[]	`["typescript", "javascript", "python", "go", "java"]`	Languages the token scanner recognizes. Pretense only mutates identifiers in files that match these languages. Unrecognized files pass through unchanged. Example: `["typescript", "javascript", "python", "go", "java"]`
`mutation.exclude`	string[]	`["*.test.ts", "node_modules"]`	Glob patterns for files and directories to skip during scanning. Patterns follow micromatch syntax. Excluded files are forwarded to the LLM without mutation. Example: `[".test.ts", ".spec.ts", "node_modules", "dist", ".pretense"]`
`mutation.preserveComments`	boolean	`true`	When true, all comment text is forwarded verbatim. Disabling this strips comments before transmission -- useful if comments contain proprietary business logic you want protected. Example: `true`
`mutation.preserveStrings`	boolean	`true`	When true, string literals are forwarded unchanged. Required for correct round-trip reversal. Only set to false if you fully understand the impact on multiline string handling. Example: `true`

secrets

Controls the secrets and PII scanner that blocks credentials from leaving your machine.

Field	Type	Default	Description
`secrets.patterns`	"default" \| "strict" \| "off"	`"default"`	Built-in pattern set to use. "default" covers 30+ patterns (API keys, JWTs, AWS creds, DB connection strings). "strict" adds PII detection (emails, phone numbers, SSNs). "off" disables the secrets scanner entirely. Example: `"default"`
`secrets.customPatterns`	string[]	`[]`	Additional regex patterns to scan for. Each string is compiled as a JavaScript RegExp. Useful for internal credential formats that the built-in scanner does not cover. Example: `["CORP_SECRET_[A-Z0-9]{32}", "internal-token-[a-f0-9]{16}"]`
`secrets.blockOnDetect`	boolean	`true`	When true, any request containing a detected secret is rejected with HTTP 422 before being forwarded. Set to false to log-only mode (secrets are flagged in the audit log but not blocked). Example: `true`

audit

Controls the local audit log that records every mutation event for compliance reporting.

Field	Type	Default	Description
`audit.enabled`	boolean	`true`	Enables or disables the audit log. When disabled, no mutation events are written to disk. The SOC2 and HIPAA compliance exports require this to be enabled. Example: `true`
`audit.retentionDays`	number	`90`	Number of days to retain audit log entries before automatic pruning. Free tier: 30 days. Pro: 365 days. Enterprise: unlimited. Example: `90`
`audit.export`	"sqlite" \| "json" \| "ndjson"	`"sqlite"`	Storage backend for the audit log. sqlite (default) is recommended for single-developer use and small teams. json outputs a flat audit.json file. ndjson streams newline-delimited records for log aggregators. Example: `"sqlite"`
`audit.exportFormat`	"json" \| "csv" \| "pdf"	`"json"`	Default format when exporting audit logs via pretense audit --export. PDF export requires Pro or Enterprise tier. Example: `"json"`

rules

Per-repo custom mutation rules. Each rule targets identifiers or secrets matching a regex pattern and applies a specific action. Rules run after the built-in scanner.

Field	Type	Default	Description
`rules[].pattern`	string	`—`	JavaScript-compatible regex pattern. Tested against identifier names and string values in scanned files. Use anchors and wildcards to match precisely. Example: `"getUserPayment.*"`
`rules[].action`	"mutate" \| "block" \| "allow"	`"mutate"`	"mutate" replaces the matched identifier with a synthetic. "block" rejects the entire request with HTTP 422 if the pattern is found. "allow" whitelists a pattern and skips it even if the built-in scanner would flag it. Example: `"block"`
`rules[].note`	string	`—`	Human-readable label for this rule. Appears in audit log entries and the team dashboard so reviewers can understand why a token was handled a certain way. Example: `"Stripe secrets -- block before any LLM call"`

team

Team and plan configuration. These fields are set automatically when you connect a workspace in the Pretense dashboard. You can also set them manually for self-hosted deployments.

Field	Type	Default	Description
`team.maxSeats`	number	`1`	Maximum number of seats allowed in this workspace. The proxy enforces this limit when team members authenticate. Exceeding the limit returns HTTP 429 with a plan-upgrade message. Example: `100`
`team.plan`	"free" \| "pro" \| "enterprise"	`"free"`	Current plan tier. Controls which features are unlocked: free (local proxy + basic scan), pro (audit export, 365-day retention, webhook notifications), enterprise (SSO, on-prem, SIEM, unlimited retention). Example: `"pro"`

Environment variable overrides

Any config field can be overridden via environment variable at runtime. Env vars take precedence over config.json. Useful in CI/CD pipelines or Docker environments where editing files is not practical.

Environment variable	Config field
`PRETENSE_PORT`	`proxy.port`
`PRETENSE_TIMEOUT`	`proxy.timeout`
`PRETENSE_BLOCK_SECRETS`	`secrets.blockOnDetect`
`PRETENSE_SECRET_PATTERNS`	`secrets.patterns`
`PRETENSE_AUDIT_ENABLED`	`audit.enabled`
`PRETENSE_AUDIT_RETENTION`	`audit.retentionDays`

.pretenseignore

A gitignore-style file that tells Pretense which files and directories to skip during scans. Place it in your project root alongside .pretense.yaml. Supports glob patterns, comments, and negation.

.pretenseignore

# .pretenseignore -- files and directories to skip during scans
# Follows .gitignore syntax

# Test files
*.test.ts
*.spec.ts
__tests__/

# Build output
dist/
build/
.next/

# Dependencies
node_modules/

# Pretense internal files
.pretense/mutations.json
.pretense/audit.db

# Documentation
*.md
docs/

# Generated files
*.generated.ts
*.d.ts

•Uses .gitignore syntax: # for comments, ! for negation, ** for recursive glob

•Patterns are matched relative to the project root

•Add patterns via CLI: pretense ignore "*.test.ts"

•Commit .pretenseignore to version control so the team shares the same exclusions

~/.pretense/credentials.json

Stores authentication credentials for Pretense Cloud (team dashboard, audit sync, remote policies). Created by pretense auth login. Never commit this file.

~/.pretense/credentials.json

{
  "version": 1,
  "accounts": {
    "default": {
      "apiKey": "ptns_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "teamId": "team_abc123",
      "email": "you@company.com",
      "plan": "pro",
      "expiresAt": "2027-04-08T00:00:00.000Z"
    }
  },
  "activeAccount": "default"
}

Field	Description
`apiKey`	Your Pretense API key. Starts with ptns_live_ for production or ptns_test_ for sandbox.
`teamId`	Your team identifier. Links local scans to your team dashboard.
`email`	The email associated with your Pretense account.
`plan`	Current plan tier: free, pro, or enterprise.
`expiresAt`	ISO 8601 timestamp when the credential expires. Refresh by running pretense auth login again.
`activeAccount`	Which account to use when multiple are configured.

This file contains sensitive credentials. It is stored in your home directory, not in your project. Never commit ~/.pretense/credentials.json to version control.

Per-repository configuration

Each repository gets its own .pretense.yaml and .pretenseignore. The proxy reads the config from the directory where you ran pretense init. Commit both files to version control so your whole team shares the same settings.

your-project/
  .pretense.yaml       # commit this
  .pretenseignore      # commit this
  .pretense/
    mutations.json     # gitignore this
    audit.db           # gitignore this

Next steps

Configuration set. Here is where to go deeper.

CLI Reference

All 12 commands with flags and examples

Quickstart guide

Install and protect your workflow in 60 seconds

API Reference

Proxy endpoints and request/response schemas

Integrations

Claude Code, Cursor, VS Code, GitHub Actions

Was this page helpful?