Cover

Keep sensitive values out of LLM requests without breaking the conversation.

Install · Quick start · Policies · Monitoring · Pi / OMP · Security

Cover is a local privacy proxy for Codex, Claude Code, Cursor, SDKs, and other HTTP-based AI clients. It scans outgoing JSON, replaces matched values locally, and restores reversible replacements in JSON and streaming responses. The LLM receives the protected values, while the agent can continue using the originals.

Cover runs as a transparent reverse proxy with policy-driven replacement, deterministic pseudonyms, operational checks, Codex support, and strict failure handling. It is designed to stay local, observable, and explicit about what it cannot inspect.

flowchart LR
    A["Agent"] -->|"JSON request"| C["Cover<br/>detect · transform · enforce"]
    C -->|"protected request"| L["LLM or router"]
    L -->|"JSON or SSE response"| C
    C -->|"restored response"| A

Highlights

Install

The installer clones Cover, builds it with Go, installs it to ~/.local/bin/cover, configures selected clients, and starts the proxy.

curl -fsSL https://raw.githubusercontent.com/DavidCarliez/cover/main/scripts/install.sh | bash

Requirements: git and the Go version declared in go.mod.

Prebuilt Linux, macOS, and Windows archives and their checksums are available from GitHub Releases.

For a non-interactive install:

COVER_AGENTS=openai,claude \
  curl -fsSL https://raw.githubusercontent.com/DavidCarliez/cover/main/scripts/install.sh | bash

git clone https://github.com/DavidCarliez/cover.git
cd cover
go build -o cover ./cmd/cover
install -m 0755 cover ~/.local/bin/cover

GOOS=linux GOARCH=arm64 go build -o cover-linux-arm64 ./cmd/cover
GOOS=windows GOARCH=amd64 go build -o cover.exe ./cmd/cover

Quick start

cover init             # write ~/.config/cover/config.yaml
cover start --detach   # run in the background
cover doctor           # verify the local setup
cover test             # local redaction round trip, no network call
cover monitor          # watch privacy-safe request metadata

cover init prompts for OpenAI, Anthropic, or a custom upstream. The complete configuration is documented in configs/config.example.yaml.

Command reference

Stopping Cover does not change client configuration. A client still pointed at Cover will fail to connect until Cover is restarted or the client is pointed back to its direct provider or router.

Privacy policies

Built-in regex detection covers AWS and GCP keys, GitHub, GitLab, Slack, Stripe, and Anthropic tokens, private-key blocks, JWTs, explicit generic secret assignments, emails, SSNs, credit cards, phone numbers, and IBANs. A bare OpenAI sk-... value is deliberately not a dedicated built-in category. Define an explicit rule if your environment needs one.

Rules live under rules in ~/.config/cover/config.yaml. A selector can be a regular expression, a builtin_* detector, or a list of JSON object keys.

rules:
  password_fields:
    keys: [password, passwd, pwd, passphrase, user_password, database_password]
    category: password
    action: pseudonymize
    generator: password
    priority: 220

  ipv4_addresses:
    detector: builtin_ipv4
    category: ip_address
    action: pseudonymize
    generator: ipv4
    priority: 100

  customer_name:
    pattern: '(?i)\bNIKE\b'
    category: customer
    action: pseudonymize
    generator: alias
    priority: 80

  forbidden_secret:
    pattern: '(?i)secret\s*[:=]\s*(?P<value>[^\s,;]+)'
    action: block
    priority: 200

Key selectors protect complete string values. For example, {"password":"admin"} is protected without treating an unrelated {"username":"admin"} as a password. Named (?P<value>...) groups let a regex replace only the captured value.

Pseudonym generators: ipv4, ipv6, hostname, domain, fqdn, email, username, password, secret, uuid, url, and alias.

Rules are validated at startup. Invalid selectors, expressions, actions, generators, or capture groups prevent Cover from starting. Detector errors, mapping exhaustion, malformed JSON, compressed bodies, and explicit blocks do not fall back to forwarding the original request.

Stable pseudonyms and reversible mappings

Cover creates ~/.config/cover/pseudonym.key with owner-only permissions. HMAC-SHA-256 derives the same pseudonym for the same original value across sessions and restarts. Different installations produce different pseudonyms.

The key cannot recover original values. Restoration uses bounded mappings held only in process memory. Mappings are separated by X-Cover-Session, expire after the configured TTL, and are deleted when an isolated request completes. Back up the key only if stable pseudonym continuity matters.

Inspect, diagnose, and monitor

Preview without sending

cover inspect request.json
cover inspect request.json --session demo

The report contains the transformed request, matched rules, categories, actions, warnings, and blocked state. It does not send a network request or print the reversible mapping.

Check the installation

cover doctor
cover doctor --json

Doctor validates the configuration, listener policy, limits, pseudonym key, redaction round trip, upstream-loop protection, daemon, fail-closed behavior, audit log, environment routing, Codex provider, and Codex request compression. Its live probe is rejected locally and does not spend model tokens.

Safe monitoring by default

cover monitor
cover monitor --follow=false -n 50
cover monitor --json

The default monitor shows only allowlisted metadata: time, HTTP status, transformation count, byte counts, latency, categories, and generic errors. Audit logs never contain request or response bodies, matched values, mappings, paths, queries, or upstream credentials.

Explicit sensitive live view

cover monitor --show-content
cover monitor --show-content --once
cover monitor --show-content --json

This opt-in view shows each caught original and replacement, followed by the exact transformed JSON handed to the upstream transport. It is live-only and never added to the audit log. Capture starts after an authenticated local viewer connects and stops when it disconnects. The stream is loopback-only, uses a token derived from the installation key, and disconnects slow viewers.

[!WARNING] This terminal output is sensitive. Do not use --show-content in shared terminals, recorded sessions, CI logs, or support transcripts.

Connect clients

Cover forwards request methods, paths, queries, and headers to the configured upstream. Existing provider authentication still works because Cover does not rewrite authentication headers.

Codex and Codex Router

Codex uses the Responses API. Add a user-level provider to ~/.codex/config.toml and disable request compression so Cover can inspect the body:

model_provider = "cover"

[model_providers.cover]
name = "Cover"
base_url = "http://127.0.0.1:8317"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = false

[features]
enable_request_compression = false

These keys follow the official Codex configuration reference. If [features] already exists, add the setting to that table. For a router that reads a token from the environment, replace requires_openai_auth with env_key = "YOUR_ROUTER_KEY_ENV_NAME".

Keep Cover's upstream pointed at the real router URL. Use configs/codex-router.example.yaml as a starting point. The selected model can be OpenAI, Anthropic, Gemini, DeepSeek, or another model because Cover operates on the router's generic JSON traffic.

Responses API encrypted_content fields are opaque and cryptographically verified. Cover leaves them unchanged during request scanning and response restoration.

Claude Code, SDKs, and other clients

export ANTHROPIC_BASE_URL=http://127.0.0.1:8317
export OPENAI_BASE_URL=http://127.0.0.1:8317/v1

Claude Code uses the first form. OpenAI-compatible SDKs and clients generally use the /v1 form. The installer can persist these settings, and cover env prints the exports for the clients selected during installation.

SDK constructors can set the same base URL directly:

client = OpenAI(base_url="http://127.0.0.1:8317/v1", api_key=os.environ["OPENAI_API_KEY"])
client = anthropic.Anthropic(base_url="http://127.0.0.1:8317", api_key=os.environ["ANTHROPIC_API_KEY"])

Cursor and other applications can use the same endpoint when they expose an API base URL setting. Confirm routing with cover doctor or cover monitor.

Pi and Oh My Pi

The official harness extension controls Cover from Pi or Oh My Pi while keeping the privacy engine in the local Go proxy:

pi install npm:cover-harness
# or
omp plugin install cover-harness

Configure only the providers that must go through the current Cover upstream:

/cover providers openai-codex,deepseek=/
/cover on
/cover doctor

OpenAI-family providers default to the /v1 proxy path. =/ selects the proxy root for transports such as DeepSeek that add their own request path. Use /cover status, /cover start, /cover stop, and /cover monitor for normal operation. /cover off restores direct provider routing.

Protection is fail-closed: while enabled, configured providers remain pointed at Cover when its daemon is unavailable, so requests fail locally rather than bypassing the proxy. Extension state is private and local at ~/.config/cover/harness.json.

The same package appears in the Pi package gallery. OMP users can also add this repository as a marketplace:

omp plugin marketplace add DavidCarliez/cover
omp plugin install cover-harness@cover

Optional local LLM detector

Regex and key-aware rules cannot identify every name, address, customer ID, or internal codename. Cover can run a small local llama.cpp model as an additional semantic detector.

cover models pull
cover models status
cover restart

The default model is Qwen2.5-0.5B-Instruct in a roughly 490 MB Q4 GGUF. Cover starts llama-server on loopback and enforces per-call and overall request budgets. Missing binaries, startup failures, timeouts, and detector errors fail closed when the detector is enabled. Returned spans must occur verbatim in the input before Cover accepts them.

Leave this feature disabled on unsupported platforms. See the detectors.llm_fallback section in configs/config.example.yaml for limits, batching, concurrency, and model paths.

Security boundary

Cover protects matching string values in JSON bodies that actually pass through the proxy. It does not claim to discover every sensitive value.

Data can still leave the machine when it appears in:

• a value that no enabled detector or rule recognizes;
• a field covered by an allow rule;
• HTTP headers, URL paths, or query strings;
• image pixels, binary media, or unsupported encodings;
• non-string JSON values;
• structural protocol fields such as model, role, type, IDs, and tool or function names;
• opaque encrypted_content, which must remain unchanged for protocol safety;
• traffic from a client that bypasses Cover.

Inline image handling is configurable with media.images: allow, warn, or block. Cover does not inspect pixels, and no media policy can recognize every possible encoding.

Cover rejects non-loopback listeners unless network.allow_remote: true is explicitly configured. If Cover and its upstream router run on different hosts, use TLS or another trusted transport and apply separate network access controls. Cover itself does not authenticate ordinary proxy traffic.

Request, buffered-response, total-stream, and per-SSE-event limits bound memory use. Oversized requests return HTTP 413, oversized buffered responses return HTTP 502, and oversized streams are terminated.

Read SECURITY.md before reporting a vulnerability. Please use the private reporting route described there rather than opening a public issue.

Project

• Development and tests: CONTRIBUTING.md
• Conduct: CODE_OF_CONDUCT.md
• License: Apache License 2.0