OpenCode plugin

Keep AI agents out of your `.env` files.

envsitter-guard stops coding agents from reading or editing secret env files, then gives them fifteen envsitter tools that work with keys, fingerprints, and booleans instead of values.

OpenCode 2.0.32+ OpenCode 1.18.29+

$ opencode plugin add envsitter-guard@latest

Other install options

opencode, agent session

tool read .envblockedReading `.env*` is blocked to prevent secret leaks (`.env`). Use EnvSitter tools instead (never prints values).tool shell cat .env.localblockedShell commands that reference `.env*` files or `.envsitter/pepper` are blocked (`.env.local`).tool envsitter_keys {"filePath": ".env"}{ "file": ".env", "keys": [ "API_TOKEN", "DB_PASSWORD" ] }tool envsitter_match {"key": "NODE_ENV", "op": "is_equal", ...}{ ..., "match": true }

Install

One package for both OpenCode versions.

OpenCode 2 loads the plugin through setup() and OpenCode 1 through server(), both from the same default export. Restart OpenCode 1 after changing config; OpenCode 2 reloads watched config on its own.

OpenCode 2: opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "plugins": ["envsitter-guard@latest"]
}

OpenCode 1: opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["envsitter-guard@latest"]
}

Prefer a local file? Re-export the package from .opencode/plugins/envsitter-guard.ts (OpenCode 2) or .opencode/plugin/ (OpenCode 1). The README has the snippet.

Blocking

Every path to a secret file, closed.

Protected files are .env, .env.<anything>, <name>.env, <name>.env.<anything>, and .envsitter/pepper. Blocked calls fail with a message that points the agent to envsitter_help.

Reads and edits. Any non-envsitter tool whose path arguments point at a protected file: read, edit, write, grep on a file, MCP filesystem tools.
Patches. patch and apply_patch calls that add, update, move, or delete a protected file.
Shell commands. Commands that name a protected file, such as cat .env, source .env, echo X >> .env, or node --env-file=.env.
Search results. grep matches inside protected files are removed from the output.
Secret values in tool output. Secret-looking values from protected env files are replaced with [envsitter: KEY redacted] in every other tool's output, so grep -r, cat *, and log files do not hand them to the model.
Permission checks (OpenCode 2). read, edit, and shell checks on protected files are denied, including calls made from Code Mode.

Templates stay readable. .env.example, .env.sample, .env.template, .env.dist, and .env.default(s).
The envsitter CLI still runs. Shell calls such as npx envsitter keys --file .env are allowed because the CLI never prints values.

Tools

Fifteen tools that never return a value.

Agents call them by name. Mutations and file operations are dry runs unless the agent passes write: true, and output is limited to keys, booleans, line numbers, and plans.

Reading

envsitter_keys
envsitter_fingerprint
envsitter_scan

List keys, fingerprint one value, or detect JWT, URL, and base64 shapes.

Matching

envsitter_match
envsitter_match_by_key

Boolean checks with every envsitter operator, for one key, many keys, or all keys.

Mutations

envsitter_add
envsitter_set
envsitter_unset
envsitter_delete

Add, update, empty, or remove keys without the agent ever reading the file.

File operations

envsitter_validate
envsitter_copy
envsitter_format
envsitter_reorder
envsitter_annotate

Validate syntax, copy keys between files, sort them, or add comments.

Help

envsitter_help

A built-in guide the agent can read when a call is blocked.

Compatibility

Verified against real OpenCode builds.

Before every release, an end-to-end check runs the real OpenCode 1 and OpenCode 2 CLIs against a scripted model and confirms each blocking scenario holds.

OpenCode	Minimum	Verified	Entry point
2.x	`2.0.32`	`2.0.32`, `2.1.0`	`setup(ctx)`
1.x	`1.18.29`	`1.18.31`, `1.19.3`	`server()`

A guardrail, not a sandbox. Shell commands that reach file contents without naming the file, such as grep -r TOKEN . or cat *, are not blocked; their output is scrubbed instead. Encoded or transformed values (base64, split strings) and values that do not look secret get through.
Default pepper location only. A pepper file at a custom path is not recognized as protected.

Built on envsitter

The same tools work outside OpenCode.

Every guard tool is backed by the envsitter library and CLI, which you can use directly in scripts, CI, and your own agent integrations.

Explore envsitter

Keep AI agents out of your .env files.