Cover

Fake values go out. Real values come back.

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

Cover is a bidirectional privacy proxy for AI coding agents. It replaces
matched sensitive values locally with realistic, deterministic stand-ins
before a request leaves your machine, then translates matching fakes in normal
and streaming responses back to the originals. The model gets coherent
context; your agent and tools keep working with the real environment.

Use reversible pseudonymize or placeholder rules when the conversation must
keep working end to end. Use one-way mask or redact rules when restoration
is unnecessary, block to stop a request locally, and allow for an explicit
exception.

Supported clients include Codex, Claude Code, Cursor, Pi / Oh My
Pi, and OpenAI- or Anthropic-compatible SDKs and routers.

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

The core binary has no cgo dependency. Standard Go cross-compilation works:

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

Highlights

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 cover-plugin controls Cover from Pi or Oh My Pi while keeping
the privacy engine in the local Go proxy:

pi install npm:cover-plugin

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.

OMP users can add this repository as a marketplace:

omp plugin marketplace add DavidCarliez/cover
omp plugin install cover-plugin@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