OpenCode plugin that prevents agents/tools from reading or editing sensitive .env files, while still allowing safe inspection via EnvSitter (keys + deterministic fingerprints; never values).
One package supports both OpenCode majors:
- OpenCode 2 (
@opencode/pluginAPI, 2.0.32+): loaded through the default export'sid+setup(). - OpenCode 1 (1.18.29+): loaded through the same default export's
server().
| OpenCode | Minimum | Verified end to end | Entry point | Built-in tools covered |
|---|---|---|---|---|
| 2.x | 2.0.32 | 2.0.32, 2.1.0 | setup(ctx) |
read, write, edit, patch, shell, grep |
| 1.x | 1.18.29 | 1.18.31, 1.19.3 | server() |
read, write, edit, apply_patch, bash, grep |
"Verified end to end" means npm run test:e2e passed against that CLI: the plugin loaded, all 15 envsitter_* tools were visible to the model, and every blocking scenario held (see Development).
Reference docs:
- OpenCode 2: https://opencode.ai/v2/docs/plugins
- OpenCode 1: https://opencode.ai/docs/plugins/
OpenCode 2 (opencode.json uses plugins, plural):
{
"$schema": "https://opencode.ai/config.json",
"plugins": ["envsitter-guard@latest"]
}Or install it globally with the OpenCode 2 CLI:
opencode plugin add envsitter-guard@latestOpenCode 1 (plugin, singular; OpenCode 2 also accepts this V1 key):
{
"$schema": "https://opencode.ai/config.json",
"plugin": ["envsitter-guard@latest"]
}Restart OpenCode after updating config (OpenCode 2 reloads watched config automatically).
Accidentally printing .env contents is one of the easiest ways for an agentic workflow to leak secrets into:
- chat transcripts
- logs/tool output
- commits/patches
- screenshots / shared sessions
envsitter-guard blocks risky operations and points you to safe alternatives.
This plugin is built on top of envsitter, a library for safely inspecting and matching .env secrets without ever printing values.
This plugin provides safe EnvSitter-backed tools and blocks sensitive file access via OpenCode tool hooks.
These tools never return raw .env values:
Reading:
envsitter_keys: list keys in a dotenv fileenvsitter_fingerprint: deterministic fingerprint of a single key's valueenvsitter_scan: scan value shapes (jwt/url/base64) without printing values
Matching:
envsitter_match: boolean/shape checks and outside-in candidate matching (without printing values)envsitter_match_by_key: bulk candidate-by-key matching (returns booleans only)
Mutations:
envsitter_add: add a new key (fails if key exists)envsitter_set: set a key's value (creates or updates)envsitter_unset: unset a key's value (sets to empty, keeps the key)envsitter_delete: delete key(s) entirely from the file
File Operations:
envsitter_validate: validate dotenv syntax (no values; issues only)envsitter_copy: copy keys between env files (no values; plan + line numbers only)envsitter_format/envsitter_reorder: reorder/format env files (no values)envsitter_annotate: add comments near keys (no values)
Help:
envsitter_help: comprehensive usage guide for all tools (topics:overview,reading,matching,mutations,file_ops,all)
Notes for file operations:
- File operations are dry-run unless
write: trueis provided. - Tools only return keys, booleans, and line numbers/operation plans.
Protected files come from envsitter's path policy (isSensitiveEnvFile / isEnvSitterPepperFile):
- Protected:
.env,.env.<anything>,<name>.env,<name>.env.<anything>(e.g..env.local,api.env,config.env.local) - Readable: example/template files
.env.example,.env.sample,.env.template,.env.dist,.env.default(s) - Not env files: source files such as
app.env.ts - Always protected:
.envsitter/pepper
Blocked operations:
- Any non-EnvSitter tool whose path arguments (
filePath,path,file_path,paths) point at a protected file:read,edit,write,grepon a file, MCP filesystem tools, and so on patch/apply_patchwhen the patch adds, updates, moves, or deletes a protected file- Shell commands (
bash/shell) that name a protected file, e.g.cat .env,source .env,echo X >> .env,node --env-file=.env(envsitter CLI calls such asnpx envsitter keys --file .envare allowed) grepresults: matches inside protected files are removed from the output- Secret values in tool output: secret-looking values from the project's protected env files are replaced with
[envsitter: KEY redacted]in the result of every non-EnvSitter tool (shell,readof other files,grep, MCP tools). The plugin finds env files up to three directories deep from the project root (for a session outside a repository, the session directory), skipping dependency, build, and cache folders, and re-reads them when they change. In a home directory or at the filesystem root, only that directory's own env files are used. Folders it cannot read and files that are not valid dotenv are skipped, and a scrubbing problem never fails the tool call. Which values count as secret is decided by envsitter's redactor (see the envsitter README). - OpenCode 2 only: a permission
evaluatehook also deniesread,edit, andshellpermission checks on protected files, including tool calls made from Code Mode
When blocked, the plugin throws an error with guidance on which EnvSitter tools to use instead.
Limits: this is a guardrail against accidental reads, not a sandbox. Commands that reach file contents without naming the file (grep -r TOKEN ., cat *, variables, eval) are not blocked; their output is scrubbed instead, which catches values as written but not encoded or transformed ones (base64, split strings) or values that do not look secret. Custom pepper locations are not recognized.
Tools only operate on dotenv files (.env*, *.env, including examples) inside the current project.
- Most tools accept a
filePaththat defaults to.env. - File operations are dry-run unless
write: trueis provided.
Lists keys in a dotenv file.
- Input:
{ "filePath"?: string, "filterRegex"?: string } - Output: JSON
{ file, keys }
Example (inside OpenCode):
{ "tool": "envsitter_keys", "args": { "filePath": ".env" } }Optional filtering:
{ "tool": "envsitter_keys", "args": { "filePath": ".env", "filterRegex": "/^(API_|DB_)/" } }Computes a deterministic fingerprint of a single key.
- Input:
{ "filePath"?: string, "key": string } - Output: JSON
{ file, key, result }
Example (inside OpenCode):
{ "tool": "envsitter_fingerprint", "args": { "filePath": ".env", "key": "DATABASE_URL" } }Matches key values without printing them.
- Input:
{ "filePath"?: string, "op"?: string, "key"?: string, "keys"?: string[], "allKeys"?: boolean, "candidate"?: string, "candidateEnvVar"?: string }
- Output:
- If
keyprovided: JSON{ file, key, op, match } - If
keysorallKeys: JSON{ file, op, matches }
- If
Notes:
- Provide exactly one selector:
key,keys, orallKeys: true. - For ops that compare against a candidate (
is_equal,partial_match_*), providecandidateorcandidateEnvVar.
Examples (inside OpenCode):
{ "tool": "envsitter_match", "args": { "filePath": ".env", "key": "SENTRY_DSN", "op": "exists" } }{ "tool": "envsitter_match", "args": { "filePath": ".env", "key": "PORT", "op": "is_number" } }{ "tool": "envsitter_match", "args": { "filePath": ".env", "key": "NODE_ENV", "op": "is_equal", "candidate": "production" } }Bulk match candidates-by-key without printing values (returns booleans only).
- Input:
{ "filePath"?: string, "candidatesByKey"?: Record<string,string>, "candidatesByKeyJson"?: string, "candidatesByKeyEnvVar"?: string }
- Output: JSON
{ file, matches }
Note: provide exactly one of candidatesByKey, candidatesByKeyJson, or candidatesByKeyEnvVar.
Example (inside OpenCode):
{ "tool": "envsitter_match_by_key", "args": { "filePath": ".env", "candidatesByKey": { "NODE_ENV": "production" } } }Scan value shapes (jwt/url/base64) without printing values.
- Input:
{ "filePath"?: string, "detect"?: ("jwt"|"url"|"base64")[], "keysFilterRegex"?: string } - Output: JSON
{ file, findings }
Example (inside OpenCode):
{ "tool": "envsitter_scan", "args": { "filePath": ".env", "detect": ["jwt", "url"] } }Validate dotenv syntax.
- Input:
{ "filePath"?: string } - Output: JSON
{ file, ok, issues }
Example (inside OpenCode):
{ "tool": "envsitter_validate", "args": { "filePath": ".env" } }Copy keys between env files. Output includes a plan (keys + line numbers), never values.
- Input:
{ "from": string, "to": string, "keys"?: string[], "includeRegex"?: string, "excludeRegex"?: string, "rename"?: string, "onConflict"?: "error"|"skip"|"overwrite", "write"?: boolean }
- Output: JSON
{ from, to, onConflict, willWrite, wrote, hasChanges, issues, plan }
Examples (inside OpenCode):
{ "tool": "envsitter_copy", "args": { "from": ".env.production", "to": ".env.staging", "keys": ["API_URL"], "onConflict": "overwrite" } }{ "tool": "envsitter_copy", "args": { "from": ".env.production", "to": ".env.staging", "keys": ["API_URL"], "onConflict": "overwrite", "write": true } }Format/reorder an env file (no values in output).
- Input:
{ "filePath"?: string, "mode"?: "sections"|"global", "sort"?: "alpha"|"none", "write"?: boolean } - Output: JSON
{ file, mode, sort, willWrite, wrote, hasChanges, issues }
Example (inside OpenCode):
{ "tool": "envsitter_format", "args": { "filePath": ".env", "mode": "sections", "sort": "alpha", "write": true } }Annotate an env key with a comment (no values in output).
- Input:
{ "filePath"?: string, "key": string, "comment": string, "line"?: number, "write"?: boolean } - Output: JSON
{ file, key, willWrite, wrote, hasChanges, issues, plan }
Example (inside OpenCode):
{ "tool": "envsitter_annotate", "args": { "filePath": ".env", "key": "DATABASE_URL", "comment": "prod only", "write": true } }Add a new key to a dotenv file (fails if key already exists).
- Input:
{ "filePath"?: string, "key": string, "value": string, "write"?: boolean } - Output: JSON
{ file, key, willWrite, wrote, hasChanges, issues, plan }
Example (inside OpenCode):
{ "tool": "envsitter_add", "args": { "filePath": ".env", "key": "NEW_API_KEY", "value": "sk-xxx", "write": true } }Set a key's value in a dotenv file (creates if missing, updates if exists).
- Input:
{ "filePath"?: string, "key": string, "value": string, "write"?: boolean } - Output: JSON
{ file, key, willWrite, wrote, hasChanges, issues, plan }
Example (inside OpenCode):
{ "tool": "envsitter_set", "args": { "filePath": ".env", "key": "API_KEY", "value": "new-value", "write": true } }Unset a key's value (sets to empty string, keeps the key line).
- Input:
{ "filePath"?: string, "key": string, "write"?: boolean } - Output: JSON
{ file, key, willWrite, wrote, hasChanges, issues, plan }
Example (inside OpenCode):
{ "tool": "envsitter_unset", "args": { "filePath": ".env", "key": "OLD_KEY", "write": true } }Delete key(s) from a dotenv file entirely (removes the line).
- Input:
{ "filePath"?: string, "keys": string[], "write"?: boolean } - Output: JSON
{ file, keys, willWrite, wrote, hasChanges, issues, plan }
Example (inside OpenCode):
{ "tool": "envsitter_delete", "args": { "filePath": ".env", "keys": ["OLD_KEY", "UNUSED_KEY"], "write": true } }Get comprehensive help on all EnvSitter tools.
- Input:
{ "topic"?: "overview" | "reading" | "matching" | "mutations" | "file_ops" | "all" } - Output: Markdown documentation for the requested topic
Topics:
overview: What EnvSitter is and tool categoriesreading:envsitter_keys,envsitter_fingerprint,envsitter_scanmatching:envsitter_match,envsitter_match_by_keywith all operatorsmutations:envsitter_add,envsitter_set,envsitter_unset,envsitter_deletefile_ops:envsitter_validate,envsitter_copy,envsitter_format,envsitter_annotateall: Full guide (default)
Example (inside OpenCode):
{ "tool": "envsitter_help", "args": { "topic": "mutations" } }If you want a local plugin file in-repo (or need local overrides), create .opencode/plugins/envsitter-guard.ts (OpenCode 2) or .opencode/plugin/envsitter-guard.ts (OpenCode 1; OpenCode 2 also scans this directory):
import EnvSitterGuard from "envsitter-guard";
export default EnvSitterGuard;
export { EnvSitterGuard } from "envsitter-guard";Then create .opencode/package.json with the dependency so OpenCode can install it:
{
"dependencies": {
"envsitter-guard": "latest"
}
}Restart OpenCode; files in .opencode/plugins/ (and .opencode/plugin/) are loaded automatically.
Place a plugin file in ~/.config/opencode/plugins/ (OpenCode 2) or ~/.config/opencode/plugin/ (OpenCode 1) if you want it enabled for all projects.
(You can use the same contents as Option B.)
npm cinpm run typechecknpm testnpm run test:e2escripts/e2e-opencode.mjs builds the plugin, then runs the real opencode (1.x) and opencode2 (2.x) CLIs against a scripted OpenAI-compatible model served on 127.0.0.1. For each version it checks what the model gets back from each tool:
envsitter_keyslists keys without values, and all 15envsitter_*tools are offered directlyreadof.envis blocked,readof.env.exampleis allowedwriteto.envand a patch adding.env.localare blocked, and the files stay untouchedcat .envthrough the shell tool is blockedcat logs/app.logthrough the shell tool andreadof that log return the token in it as[envsitter: API_TOKEN redacted]grepresults omit matches inside.env
Each version runs in its own temporary HOME with fake secrets, so your real config, credentials, and session database are never read or modified, and no paid model is called. A version whose CLI is missing is skipped. CI runs the check against the minimum and latest-tested versions on every push, and .github/workflows/e2e-latest.yml runs it weekly against the newest opencode-ai and @opencode/cli releases.
| Variable | Default | Purpose |
|---|---|---|
OPENCODE_V1_BIN |
opencode |
OpenCode 1 CLI to test |
OPENCODE_V2_BIN |
opencode2 |
OpenCode 2 CLI to test |
KEEP_E2E |
unset | 1 keeps the temporary projects for inspection |
E2E_REQUIRE_ALL |
unset | 1 fails instead of skipping when a CLI is missing (CI sets it) |
The OpenCode 2 curl installer replaces the OpenCode 1 binary. To keep both, install OpenCode 2 from npm into its own prefix; the package also ships an opencode2 command:
npm install -g --prefix ~/.local/opt/opencode2 @opencode/cli
~/.local/opt/opencode2/bin/opencode2 --versionOpenCode 2 reads the same config and data directories as OpenCode 1 and, by default, the same opencode.db, which it migrates in place. Give it its own database unless you mean to migrate:
OPENCODE_DB=opencode-v2.db ~/.local/opt/opencode2/bin/opencode2npm run buildReleases are published by GitHub Actions with npm trusted publishing, so no npm token is stored anywhere and every version ships with a provenance attestation.
- Release
envsitterfirst when this version depends on a new one, then runnpm installhere sopackage-lock.jsonpicks it up. - Bump
versioninpackage.jsonand replace(Unreleased)in the matchingCHANGELOG.mdheading with the release date. - Commit, then push a matching tag:
git tag v0.1.0 && git push origin main v0.1.0. - The Release workflow reruns CI, including the OpenCode 1 + 2 end-to-end check (pinned in
.github/workflows/ci.yml), checks that the tag,package.json, and the CHANGELOG agree, publishes to npm (prereleases go to thenextdist-tag), and creates the GitHub Release from the CHANGELOG section.
- envsitter — The underlying library this plugin is built on. Provides CLI and programmatic API for safe
.envinspection. - EnvSitter CLI:
npx envsitter keys --file .env(alternative to plugin tools)
- This project intentionally avoids reading or printing
.envvalues. - All tools return keys, booleans, line numbers, and operation plans — never secret values.
MIT. See LICENSE.