DEV Community: Oluwafemi

Same logs, no secrets: penv 1.0.0-rc.3

Oluwafemi — Wed, 30 Sep 2026 13:30:47 +0000

This is a debug log most services have somewhere:

INFO   shop-api 2.4.1 · production
DEBUG  db postgres://shop:vR2x9Lq7Tz4W@prod-db/shop
DEBUG  stripe sk_live_51Nq8xZ2eVbT4kP0aLm
INFO   listening on :3000

It ends up in terminal scrollback, CI logs, a pasted bug report, and the context of any coding agent that ran the command. The clip below takes that app from node --env-file=.env to penv run in about 30 seconds. Everything in it runs locally, with no account.

1. Write the schema

penv init

This reads .env, writes .env.schema (key, type, required, sensitive), adds .env and .env.* to .gitignore, and writes deny rules for any coding agent it detects. In the clip that is .claude/settings.json. The schema is a plain @env-spec file, the same format varlock reads.

2. Run through penv

penv run -- node server.js

The logs are the same, but the secret values are masked. Masking is on by default in every penv run. It also works inside Node, Bun, Deno and Python through a preload, so it covers console and Response bodies, not only the terminal.

If git tracks the .env, penv run says so and prints the fix:

git rm -q --cached .env && git commit -qm "stop tracking .env"

3. Find the copies

penv scan

penv scan finds secret values that were committed to other files. In the clip it catches config/staging.env.bak:3 holding STRIPE_SECRET_KEY. Remove the value, rotate it if it was ever pushed, and read it from penv run instead.

rc.3: masking broke Next.js middleware

With mask = true, the generated env.ts and the penv run preload mask Response bodies through a subclass of Response. A NextResponse built on the original class then failed Next's instanceof Response check, and every request answered 500. rc.3 keeps instanceof Response working.

Behaviour has been frozen since 1.0.0-rc.1. Only fixes land before 1.0.0. See the stability promise.

With penv.cloud

In cloud mode, rc.2 adds checks on what penv injects:

A key that would change how the command runs, such as NODE_OPTIONS, LD_PRELOAD, BASH_ENV, PATH or PIP_INDEX_URL, fails the run with reserved_name (exit 3) instead of being injected.
Your command never inherits a CI runner's OIDC request token, GITHUB_ENV/GITHUB_OUTPUT/GITHUB_PATH/GITHUB_STATE, INPUT_* or STATE_*.
penv login makes you type the code your terminal shows. A link alone can't approve someone else's terminal.

penv.cloud opens soon.

Install

curl -fsSL https://penv.cloud/install | sh
penv upgrade next     # already installed

This article was drafted with AI from the penv release notes and checked against them.

penv 1.0.0-beta.1: project and env commands, a terminal UI, and what "beta" means here

Oluwafemi — Tue, 22 Sep 2026 08:43:50 +0000

Your coding agent can read .env. It also reads what it prints.

penv is a single Rust binary that validates a schema before your process starts, and keeps secret values out of files, the repo, shell history and agent output. 1.0.0-beta.1 shipped today.

npm i -g @penvhq/cli@next
# or
curl penv.cloud/install | sh

Repo: github.com/penvhq/penvhq · Release: v1.0.0-beta.1

Start without an account

penv init
penv run -- npm run dev

penv init writes one committed file, .env.schema. It is a varlock @env-spec file; the decorators (@type, @required, @sensitive, …) are documented at varlock.dev/env-spec/reference. Migrating an existing .env into one: this guide.

A value that fails the schema exits 3 before npm run dev starts.

Under an agent

penv guard

Detects the running harness and writes its deny rules for .env and .env.*. Claude Code, Codex, Cursor, Copilot CLI, Gemini, Amp, Cline, Windsurf. --all writes every one. What each harness actually reads: Eight coding agents, eight deny-list formats.

Inside an agent session, penv run masks secret values in the child's stdout and stderr: raw, hex, base64 and URL-encoded forms. penv reveal is refused. Output is JSON.

New in beta.1

`penv project` and `penv env`

penv project ls | new | rename | rm
penv env     ls | new | rename | copy | rm
penv ls --env staging

-p <project> is optional inside a linked folder. rm asks a person to type the name. From an agent or a pipe it exits 4 and prints the command to run.

Terminal UI

Pickers, spinners on network calls, tables, and refusals written as sentences. Drawn on stderr, only when a person is at a TTY. Piped, JSON and agent sessions get the same plain lines as before.

`penv push` refuses before the server is contacted

refusal	when
`nothing_to_push`	`.env` is missing or has no values. An empty first push no longer creates a project.
`no_such_environment`	`--env` names an environment the project does not have. Lists the ones that exist.
`org_mismatch`	`--org` contradicts the schema's `@penv=` header. Previously ignored.

A new project is created with the environment being pushed, not only development.

`penv pull`

Values containing quotes and line breaks round-trip, written in whichever literal quote the value lacks.
A \r in the file no longer blocks the pull.
A partial write reports the keys it skipped instead of failing the whole pull.
A folder with no @penv= header can be linked to a project the account already has.

Also

Dynamic value injection fixed for Next.js.
Release notes are generated from merged PRs; npm provenance verifies against penvhq/penvhq.

What beta means here

No more breaking changes planned before 1.0.
Bugs expected. Issues are open.
@since, @rotate and @dynamicFrom semantics get documented at RC.

MIT. One static binary. No runtime.

Disclosure: this post was generated by an AI from the release changelog on GitHub and reviewed before publishing. If anything here disagrees with the code, the changelog is right and I'd appreciate a comment pointing it out.

You can migrate your existing .env into varlock’s .env.schema using penv Guide: https://github.com/penvhq/penvhq

Oluwafemi — Sat, 19 Sep 2026 07:48:22 +0000

GitHub - penvhq/penvhq: The penv cli, a schema-first secrets tooling for humans and coding agents. One static binary: validates .env before your process starts, generates typed access, and guards agent harnesses. · GitHub

The penv cli, a schema-first secrets tooling for humans and coding agents. One static binary: validates .env before your process starts, generates typed access, and guards agent harnesses. - penvhq...

github.com

Eight coding agents, eight deny-list formats. What each one actually reads.

Oluwafemi — Tue, 15 Sep 2026 13:41:07 +0000

Every coding-agent harness has a deny list. Almost nobody sets it, because each tool wants a different file, a different syntax and a different idea of what "deny" means.

I went through all of them while building penv guard. This is the audit, as of September 2026. Use it even if you never install penv.

The threat is boring

Your agent runs as you. If you can cat .env, so can it. It doesn't need to be malicious: a grep for context, an env while debugging, a stack trace with the environment attached. The value ends up in a transcript on someone else's server.

A deny rule stops the read. It does not stop the value leaking once it's in the process. Keep both problems in your head; this post is only about the first one.

What each harness wants

Two patterns, everywhere: .env and .env.*. Not *.env, not .env.local spelled out. The second one is the whole point: a rule on .env alone does nothing for .env.local, .env.production, .env.bak.

Claude Code

File: .claude/settings.json (project). Two mechanisms, and you want both.

{
  "permissions": { "deny": ["Read(./.env)", "Read(./.env.*)"] },
  "sandbox": { "filesystem": { "denyRead": ["./.env", "./.env.*"] } },
  "hooks": {
    "PreToolUse": [{ "matcher": ".*", "hooks": [{ "type": "command", "command": "penv hook claude-code" }] }]
  }
}

permissions.deny is checked by the tool layer. sandbox.filesystem.denyRead is enforced by the OS sandbox on macOS and Linux. Native Windows has no Claude Code sandbox, so only the deny rules and the hook apply there.

There's also a user-scope file, ~/.claude/settings.json, where you can list env vars to mask with {"name": KEY, "mode": "mask"}. penv prints that block and tells you to paste it; it does not write outside your repo.

The hook answers on stdout with permissionDecision: "deny" and exit 0. Get that wrong and the hook is ignored.

Codex

File: .codex/config.toml.

[sandbox_workspace_write]
deny_read = ["**/.env", "**/.env.*"]

[shell_environment_policy]
inherit = "core"
ignore_default_excludes = false

Glob, not path. **/ because Codex resolves from the workspace root. The shell_environment_policy block matters as much as the deny: inherit = "core" keeps Codex from handing your whole environment to every subprocess.

Cursor

Two files. .cursor/cli.json:

{ "permissions": { "deny": ["Read(.env)", "Read(.env.*)"] } }

and .cursor/hooks.json:

{
  "hooks": {
    "beforeReadFile": [{ "command": "penv hook cursor", "failClosed": true }],
    "beforeShellExecution": [{ "command": "penv hook cursor", "failClosed": true }]
  }
}

failClosed: true is the line that matters. Without it, a hook that crashes is a hook that allows.

GitHub Copilot CLI

File: .github/copilot/permissions-config.json.

{ "permissions": { "deny": ["Read(**/.env)", "Read(**/.env.*)"] } }

Honest note, and it's in penv's own template comment: Copilot hasn't published a schema for this file. The shape above is best effort until they do.

Gemini CLI

File: .gemini/settings.json. Hook on run_shell_command, PreToolUse. Same idea as Claude Code, different matcher name.

Amp

File: .amp/settings.json.

{ "amp.guardedFiles.allowlist": [] }

Amp inverts the model: it guards files by default and you allow exceptions. An empty allowlist means nothing is exempt. penv only writes this file if it's absent, so an allowlist you already curated is left alone.

Cline

File: .clinerules/hooks/PreToolUse. A two-line /bin/sh script:

#!/bin/sh
exec penv hook cline "$@"

Must be executable. Denies on stderr, exit 2.

Windsurf

File: .windsurf/hooks.json. Two hooks, pre_run_command and pre_read_code, both pointing at penv hook windsurf.

Three things I got wrong the first time

The hook must be a binary, not a script. A node hook.js or python hook.py fails open when the interpreter is missing or the wrong version. penv hook <harness> is the penv binary itself; the only script in the whole set is Cline's two-line shim, because that's the only shape Cline accepts.

Deny replies are not uniform. Claude Code and Cursor want the decision on stdout with exit 0. Everyone else wants stderr and exit 2. Answer on both streams, or neither, and you're guessing what the harness does with it.

Empty stdin is the only allow. If the hook can't parse the payload but there was something to match on, it refuses. Fail closed, always.

What `penv guard` does with all this

It doesn't write eight files onto your machine. It probes for what's installed: a .claude or ~/.claude folder, a codex on PATH, and so on for each. Then it writes the guard for those and only those.

$ penv guard
HARNESS      INSTALLED  FILE                    STATUS
claude-code  yes        .claude/settings.json   written
codex        yes        .codex/config.toml      written

penv guard --check shows the same table without writing, and exits non-zero if anything is stale, so it works as a CI step. penv guard cursor targets one. penv guard --all writes every harness penv knows, for a template repo.

Merges are per-file, not per-harness. JSON deny lists are unioned with what you already have. TOML and the Cline script are append-unique. Amp is replace-if-absent. Your existing config survives.

Two invariants are tested on every render: the patterns are exactly .env and .env.*, never a list of filenames; and no rendered guard may contain .env.local (enumerating filenames is how you miss one) or .env.schema (the schema is the one file the agent should read).

The part the deny list can't do

Once a value is in your process, no deny rule helps. That's the other half: penv run -- your-app injects values at exec time and, when it detects an agent driving, masks every secret in the child's stdout and stderr in 14 encodings (raw, hex, base64 at three phases, URL-encoded, JSON-escaped). Different post.

The security claim penv prints, verbatim, from penv guard --check:

penv validates your .env, keeps values out of your agent's output, and blocks it from reading the file where its harness allows.

"Where its harness allows" is doing real work in that sentence. That's this post.

penv is MIT, one static Rust binary, no account needed for local mode.

OSS: https://github.com/penvhq/penvhq
Install: curl -fsSL penv.cloud/install | sh or npm i -g @penvhq/cli

If your harness isn't in the list, or one of these shapes is wrong, say so in the comments. The guard folder is data, so a fix is a PR to one guard.toml.