DEV Community: penv

Why penv adopted @env-spec instead of inventing a schema format

penv — Mon, 14 Sep 2026 13:01:00 +0000

Every tool that touches .env eventually wants a schema. You need to know that DATABASE_URL is a URL and PORT is a number, which keys are required, and, if you care about coding agents at all, which values must never be echoed. The obvious move is to design a little format for that. We nearly did.

Then we read @env-spec.

What @env-spec is

@env-spec is the decorator vocabulary that varlock introduced: comments above a key in a dotenv-shaped file, carrying metadata the loader can act on.

# @type=url
DATABASE_URL=

# @type=port @sensitive=false
PORT=3000

That is the whole idea. The file still parses as dotenv. Every editor already highlights it. A person who has never seen the spec reads it correctly on the first try, and a person who has seen it reads it instantly.

We did not think we could improve on that, so we didn't try. penv's .env.schema is an @env-spec file.

What that bought us

Zero learning curve for the committed file. The thing penv puts in your repo is the thing people most need to trust and edit. Making it a format with an existing spec and an existing community meant we never had to write "how to read a .env.schema" docs. The decorators mean what the spec says they mean.

A guessable init. penv init reads the .env you already have, writes the schema next to it, and gitignores .env. Because the output is dotenv-shaped, the guesses it makes are visible and correctable in the same file: if it marks a key sensitive that isn't, you change one decorator. Every key is sensitive and required unless a bundler prefix (NEXT_PUBLIC_, VITE_, EXPO_PUBLIC_ and friends) or a dull value (3000, us-east-1) says otherwise, and a key named like a secret (STRIPE_SECRET_KEY, ..._ANON_KEY) stays sensitive whatever it holds and whatever prefix it carries.

Interoperability we didn't have to negotiate. A team that already uses varlock can drop the same file into penv. A team that leaves penv walks away with a file another tool understands. That last part matters to us more than it sounds; one of the principles in our design doc is "drop-in or evict", and a proprietary schema format would have quietly broken the evict half.

What we added

penv needs a few things the base vocabulary does not carry, so it reads three extra decorators, @since, @rotate and @dynamicFrom, plus two headers. @schema=1 names the grammar version the file was written in. @penv=<org>/<project> names the cloud project the schema belongs to; leave it out and penv runs in local mode, and nothing leaves your machine.

They follow the same shape as the spec's own decorators on purpose. A varlock user seeing @rotate for the first time will not know exactly what penv does with it, but will know exactly where it goes and how to read it. We'll document their semantics fully with the release candidate rather than half-document them now.

The one thing we left out, on purpose

This came up publicly this week, from the people who wrote the spec, and it deserves a straight answer.

varlock can set values in the schema and load a cascade of env files: .env, .env.local, .env.production, and so on, layered in a defined order. It is a useful model and a lot of teams rely on it.

penv does not do the cascade. It reads exactly one local file, .env, from the directory that holds the schema, and no .env.* variant is ever layered on top. There is one committed schema, one local .env (which penv init gitignores), and, once you push, environments live in the cloud, addressed as org/project/environment.

The reason is the problem penv was built for. A coding agent runs as you, and the deny rules people write by hand for their harnesses are almost always written against .env, singular. .env.local and .env.production are precisely the files those rules miss, and precisely the files that hold the interesting values. penv's own guards deny .env.* as a pattern across eight harnesses, so the cost is not enforcement. The cost is surface: every extra file in a cascade is another place a value can live and another file a grep for context can surface. We would rather have one file to keep out of reach than a well-ordered set of five.

So: non-sensitive values do live in the schema (PORT=3000 and DEBUG=true go straight in during init). Anything that could be a secret never does. And the layering that varlock does well on a laptop, penv moves to the server, where a value can be short-lived, scoped and attributed to the session that used it.

That is a real trade. It makes penv less flexible on a single machine than varlock is. If a team's workflow is built around the cascade, varlock is the better fit, and we would say so.

Why not just use varlock, then

Because they are solving adjacent problems, not the same one. varlock is the schema and the local loader, done well. penv is downstream of that: the per-harness guards, the output masking under an agent session, the typed codegen, and the path to a shared store when there is more than one laptop. We adopted the spec so that those layers sit on a format that isn't ours, and so that nobody has to choose a schema dialect in order to choose a tool.

If you're building something that touches .env, our unsolicited advice is the same thing we did: read @env-spec before designing a format. The spec is small, it's readable, and the people behind it clearly intended for others to build on it.

penv: https://github.com/penvhq/penvhq (MIT, 1.0.0-alpha.3)
@env-spec and varlock: https://varlock.dev

Disclosure: penv and varlock are separate projects. We have no affiliation beyond having adopted their spec and having argued with them, politely, on X.

Your coding agent can read your .env. Here's what we did about it.

penv — Thu, 10 Sep 2026 15:41:20 +0000

Run claude, codex, cursor, amp, whatever. It starts a shell as your user. Your user can read .env. So the agent can read .env.

That is the whole problem. Not a bug in any harness, not a jailbreak, just the permission model working as designed. And it means that whenever an agent greps around your repo for context, or a tool call echoes the environment, or a stack trace lands in a transcript, your Stripe key can go with it.

Most harnesses have a deny list you can configure. Almost nobody does, the syntax differs per tool, and a deny rule on .env does nothing about .env.local, .env.production, or the fact that printenv in a hook still works.

We built penv because we were tired of hand-writing those configs and then not trusting them.

What penv actually does

One static Rust binary. No runtime, no daemon, no account required for the first minute.

curl -fsSL https://penv.cloud/install | sh   # or: npm i -g @penvhq/cli
penv init                                    # reads .env, writes .env.schema, gitignores .env
penv run -- pnpm dev                         # validates, injects, masks

init writes exactly one file into your repo, .env.schema. It looks like this:

# @schema=1

# @type=url
DATABASE_URL=

# @type=string
STRIPE_SECRET_KEY=

# @type=port @sensitive=false
PORT=3000

No values that could be secrets are ever copied in. Every key is sensitive and required by default; a bundler prefix like NEXT_PUBLIC_ or an obviously dull value like 3000 flips that, and a key named like a secret (STRIPE_SECRET_KEY, ..._ANON_KEY) stays sensitive no matter what it holds. The decorators follow the @env-spec vocabulary, so if you have used varlock you can already read it.

The schema is committed. .env is not. That split is what makes the rest possible.

What that gives you against an agent

Validation before exec. penv run checks every value against the schema before your process starts. A missing or malformed key fails with exit code 3, not a runtime error forty seconds in.

Masking. When penv detects an agent session (it reads the harness env vars first, then walks process ancestry), it scrubs every sensitive value from the child's stdout and stderr — raw, hex, base64, and URL-encoded forms. The agent sees ***, not the key.

Harness guards, generated. penv guard writes what each harness actually enforces, from the schema:

deny rules and a sandbox block for Claude Code
a permission profile for Codex
deny rules and fail-closed hooks for Cursor
the equivalents for Copilot CLI, Gemini, Cline, Windsurf, and Amp

The hook is the penv binary itself, never a shell script that fails open when something goes wrong.

Typed access. penv gen ts or penv gen py writes a typed accessor for your language so code stops doing process.env.FOO! and reads through a validated object. Targets are folders with a template; adding a language is adding a folder.

The claim, and only the claim

penv guard --check prints one sentence, and we keep it exactly true:

penv keeps secrets out of the files, the repo, the shell history and the captured output an agent reads.

That is the layer where leaks actually happen — a grep, a transcript, a pasted stack trace — and it is the layer penv closes. penv is not a sandbox and does not claim to be one; the process you launch still runs as you. So the cloud side is built for that: every value it issues is short-lived, scoped to the session, and attributable to it. A value that escapes is already expired and already traced.

The cloud is the upgrade, not the product

Everything above works with zero account. When you have a team:

penv login   # device code in the browser
penv push    # values go to penv.cloud, .env is deleted

From there .env is a view you can regenerate, not the source of truth. A teammate clones and runs penv run -- pnpm dev; that is the onboarding. CI presents its OIDC token and gets a fifteen-minute credential. A server with nothing to present enrols a keypair once. penv reveal KEY under an agent session needs a human to click approve in the console — the agent can ask, it cannot self-serve.

Status, honestly

@penvhq/cli is at 1.0.0-alpha.3. It is published, signed, builds for macOS/Linux/Windows on x86_64 and arm64, and we use it daily. We do not expect further breaking changes before RC, but it is an alpha. Local mode needs nothing from us.

penv.cloud is in private beta. We are letting early users in from the waitlist in small batches, and the teams we onboard during the beta keep enterprise-tier benefits at launch — if you want your team on it, sign up.

If you run a coding agent against a repo with a .env in it — and you almost certainly do — try penv init on it and read the schema it writes. If it guesses a key wrong, that is a bug report we want.

Source: https://github.com/Itzfeminisce/penvhq
Install + waitlist: https://penv.cloud
npm: https://www.npmjs.com/package/@penvhq/cli

MIT.