Coding agents

Set up Claude Code, Codex or Hermes Agent to use a project's secrets without seeing them

Read this before letting Claude Code, OpenAI Codex or Hermes Agent work in a project that keeps its secrets in enveil.

The threat

An agent works by running commands and reading their output. Whatever a command prints lands in the transcript, in logs, and possibly in a model provider's history. enveil get DATABASE_URL run by an agent is a disclosure, even when nobody meant it as one.

So the rule an agent follows with enveil is run, don't read:

  • enveil run -- cargo test puts the secrets in the child's environment and prints none of them.
  • enveil list, enveil history KEY and enveil whoami show names, versions and scopes, never values. They are free to call.
  • enveil get, enveil pull, cat .env, and env or printenv under enveil run are what an agent avoids, unless the person explicitly asks to see a value.
  • A bad rotation is undone with history and rollback, which never decrypt the value for the caller.

The skill teaches this, the Claude Code hook enforces part of it, and a scoped machine identity bounds what is left.

Install the skill

The CLI carries the skill built in, so what it describes matches the installed version:

sh
enveil skill install --claude    # .claude/skills/enveil/SKILL.md in this directory
enveil skill install --codex     # .agents/skills/enveil/SKILL.md in this directory
enveil skill install --hermes    # ~/.hermes/skills/enveil/SKILL.md, always under ~
enveil skill show                # print it instead

--global installs --claude and --codex under your home directory (~/.claude/skills/enveil, ~/.agents/skills/enveil) so every project sees it. --force overwrites an existing file; without it, the install refuses.

Claude Code: the plugin

For Claude Code, the plugin brings the same skill plus a guard hook. Prefer it over skill install --claude:

sh
claude plugin marketplace add hauju/enveil
claude plugin install enveil@enveil

The hook runs before every Bash tool call (PreToolUse, matcher Bash). It is silent, and lets the command through untouched, unless the working directory or one of its parents has an .enveil.toml. Inside such a project it blocks, with exit code 2 and a reason Claude sees:

Blocked Example What it suggests
enveil get enveil -p acme get STRIPE_KEY enveil run -- <cmd>
enveil pull enveil pull --force enveil run -- <cmd>
printenv, or env on its own, under enveil run enveil run -e prod -- env | grep KEY enveil list for key names
cat, less, more, head, tail or bat on a .env file tail -n 5 ../.env.production enveil list or enveil run

It lets through cat .env.example (and .sample, .template, .dist), env RUST_LOG=debug cargo test under enveil run, ls -la .env, and everything outside an enveil project. It reads the command with jq when available; without jq it matches the raw JSON, which can only block more, never less.

Rules in AGENTS.md and CLAUDE.md

enveil init --agents also appends a short block to AGENTS.md and CLAUDE.md next to the new .enveil.toml, creating them if missing:

markdown
<!-- enveil -->
Secrets come from enveil: run commands as `enveil run -- <cmd>`.
Never `cat .env`, `enveil get`, `enveil pull`, or `env`/`printenv` under `enveil run`.
`enveil list`, `enveil history KEY` and `enveil whoami` show no values and are safe.
A read budget refusal (exit code 4) is not retryable: stop and tell the user.
<!-- /enveil -->

A file that already contains <!-- enveil --> is left alone, so running it twice adds nothing.

Give the agent its own credential

By default an agent in your terminal acts as you: your enveil login reaches every project you can, except that a member's login cannot read or change values in a protected environment such as prod. Give it a machine identity scoped to what the task needs instead.

1

Mint the identity (you, not the agent)

sh
enveil identity create --name claude-acme --scope acme-api:dev \
  --capability proxy --expires 30d

Only the evl_… token goes to stdout; the id, scopes and expiry go to stderr. Repeat --scope for more, and use --scope acme-api for every environment. --budget 60/600 sets reads per minute and hour. This needs your login with an admin role: a machine token is refused with a 403, so an agent cannot mint itself more access.

2

Restrict the API keys to their hosts

sh
enveil hosts STRIPE_SECRET_KEY api.stripe.com

A proxy identity can only use secrets that have allowed hosts, and only through proxy mode. It cannot read them.

3

Hand the token to the agent

Start the agent with ENVEIL_TOKEN=evl_… in its environment. ENVEIL_TOKEN wins over the keychain, so the agent acts as the identity, not as you. With a proxy-only token, plain enveil run switches to --proxy by itself and says so on stderr.

enveil run removes ENVEIL_TOKEN from the child's environment, so the command it starts cannot use the token to fetch more.

What an agent can check

enveil whoami prints who the credential is: user or machine identity, organization, role, one line per scope, expiry and read limit. It needs no .enveil.toml, so an agent can run it first.

--json prints one JSON document for list, history, projects, environments, hosts KEY and whoami. It never contains a value; agents should parse it instead of the text.

Agents should branch on the exit code, not the message. run exits with the command's own status, so these mean enveil failed only when the command never started:

Exit Meaning What to do
1 No .enveil.toml, or any other failure Read the message
2 No credential, or the session expired Ask the person to run enveil login
3 401 / 403: no scope for this, or a protected environment Check enveil whoami. For a protected environment, ask an admin; do not work around it
4 Read budget or rate limit exceeded Stop and tell the person; do not retry in a loop
5 Project, environment or secret not found Also what an unscoped project looks like; check enveil projects

MCP servers that need keys

Wrap the MCP server process, not the agent, so the agent's shell never sees the keys. -p names the project, so no .enveil.toml is needed in whatever directory the agent starts from:

json
"dataforseo": {
  "command": "enveil",
  "args": ["run", "-p", "accounts", "--proxy", "--", "bunx", "dataforseo-mcp"],
  "env": {"ENVEIL_SERVER": "https://enveil.oxidt.com"}
}

--proxy fits here: an MCP server usually talks to one API host. To let the agent reach enveil itself over MCP, see MCP server.

What stays the person's job

  • enveil login and enveil login --device: they open a browser or need a code approved. An agent without a credential should ask for ! enveil login.
  • Typing values: enveil set KEY with no value prompts hidden. An agent asks for this rather than taking a value in chat or passing one as an argument.
  • Minting and revoking identities, and changing a secret's allowed hosts. Widening hosts to make something work is a decision, not a fix.
  • Reacting to a budget refusal. It is intended behavior; an agent reports it.
  • Deleting local .env files after an import.