Keep agents out of .env

Your coding agent reads what you read. penv adds four controls: harness rules that deny .env, masking in every penv run, sealed runs for keys with @hosts, and your approval before any value prints. Agent detection: coding agents.

penv guard
penv guard --check

penv guard writes what every installed harness enforces, from your schema. --check reports coverage only; penv check runs it too.

Harness rules

Since beta.2 the rules also deny penv's local key file, ~/.config/penv/local.key: with it, an encrypted .env reads as plain text. The hook refuses a penv/local.key path anywhere, %APPDATA% included.

Merging is additive, idempotent, and never weakens an existing rule. guard --check reports each file as current, stale, missing or overridden by the existing file; anything but current exits 3.

For Claude Code, guard also prints a block listing every sensitive key with "mode": "mask". Paste it into your ~/.claude/settings.json; it lives outside the repository.

Hook

The installed hook is penv hook <harness>, the binary itself. A script would fail open when its interpreter is missing. Claude Code, Cursor, Gemini, Cline and Windsurf run it; Codex, Amp and Copilot CLI get rules only.

A .env refusal names penv ls for key names and penv check for what is missing.

Agent session behavior

Point your agent at penv run instead of pull: values reach one child process, never disk. Every cloud request from an agent session carries the harness name and session id, so our audit log names both.

Masking

Since beta.2 penv run masks on every run, your terminal and CI included. It scrubs the child's stdout and stderr as they stream, across chunk boundaries, and preloads masking into Node, Bun, Deno and Python processes.

A match becomes the value's first two characters and a run of blocks.

--no-mask and --no-preload work only when stdin and stdout are both terminals and no agent is detected; otherwise penv ignores them and says so. Masking stops accidental leaks, not code written to disguise a value. The GIT_EDITOR trigger: environment variables.

Sealed runs

# @type=string(startsWith=sk_live_, minLength=32) @hosts=api.stripe.com
STRIPE_SECRET_KEY=

A key with @hosts reaches the command as a placeholder shaped by its type. A proxy inside penv run puts the real value into the request line, headers and body sent to the named hosts only; a value echoed back returns as the placeholder.

@hosts is a penv addition: schema format.

Approve a reveal

penv reveal STRIPE_SECRET_KEY

{
  "error": "approval_required",
  "message": "STRIPE_SECRET_KEY needs a person to approve the reveal.",
  "approval": "apr_example",
  "url": "https://penv.cloud/approvals/apr_example",
  "expiresAt": "2026-09-10T12:40:00Z",
  "fix": "A person approves at https://penv.cloud/approvals/apr_example, then run penv reveal STRIPE_SECRET_KEY --approval apr_example."
}

penv reveal STRIPE_SECRET_KEY --approval apr_example

See the four approval codes.

A completed reveal writes four entries to our audit log: secret.reveal_requested, secret.reveal_approved (or secret.reveal_denied), secret.read, and secret.reveal naming the approver beside the session. When we refuse a redemption we add secret.reveal_refused.

Limits

In cloud mode penv guard --check states the limit: penv cannot stop a process running as you from looking. A guard is only as strong as the harness enforcing it.

Setup checklist

1. penv guard, then commit the written files.
2. Claude Code: paste the printed block into ~/.claude/settings.json.
3. penv guard --check until every file is current.
4. penv push, so no .env remains.
5. Add @hosts to keys your agent's commands call an API with.
6. Tell your agent to use penv run -- <command>.

GitHub Actions