Env pattern — .env is single source, MCPs read system env vars

decision Fri Jul 03 2026 00:00:00 GMT+0000 (Coordinated Universal Time) decisionenvmcpsecretssopsauth

.env single source, MCPs read system env

Decision

.env is the sole authoritative store of every secret consumed by MCP servers and agents. .env.enc (sops+age) is the committed encrypted form. Windows Scheduled Task exports every key to user-scope env at logon + daily 09:00. Every MCP config references secrets via ${env:VAR_NAME} only.

Why

Six problems this solves at once:

No secret duplication — one .env.enc, one export flow, N MCPs read from same env.
No per-agent auth-file sprawl — CC's settings.local.json, OpenCode's auth.json, Kilo's SecretStorage all read from same env vars.
Portable across machines — clone workspace, import age key from Bitwarden, run bootstrap → all secrets flow.
Rotation friendly — update .env.enc, commit, push → other machines pull, next daily task picks up.
Fleet-agnostic — adding a new agent adds a new MCP config that references ${env:VAR} — no new secret-management code.
CI-friendly — GHA sets same env vars from repo secrets; workflows unchanged when secrets rotate.

What NOT this decision covers

Anthropic OAuth refresh tokens (~/.claude/.credentials.json) — CC-managed, per-machine, re-auth via claude login. Not shipped via .env.
VS Code SecretStorage (Windows Credential Manager, Kilo API keys entered via UI) — machine-bound by design; re-auth per machine via Kilo settings UI. This is fine — the underlying provider key lives in .env, Kilo's SecretStorage caches its handle.

Alternatives rejected

Alternative	Why not
Doppler (single-source secrets service)	Card-on-file required for team tier past 3 users. Free tier fine for solo but limits growth.
Bitwarden CLI direct-lookup at MCP launch	Latency (login roundtrip) + Bitwarden session unlock UX friction on every MCP restart.
Per-agent auth files, gitignored	Duplication; every new agent adds a new secret-management surface.
Committed `.env` (public repos!)	Never.
`.env` in private submodule	Reintroduces private-repo complexity + card cost tradeoffs. `.env.enc` in public workspace is equivalent security with zero cost.

Scripts

scripts/sync-env-to-system-env.ps1 — decrypts + exports
scripts/register-scheduled-tasks.ps1 — registers Oriz-SyncEnv task

[[rules/agent/env-to-system-env-daily]]
[[decisions/agent-tooling/fleet-cc-opencode-kilo-2026-07-03]]
[[rules/security/no-hardcoded-secrets]]