Feature hasn't been suggested before.

• I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

Problem

When trying to share a reproducible OpenCode setup within my team, configs quickly become unmanageable due to hardcoded credentials. The {env:VAR} syntax exists and is perfect for this use case, but there's no built-in way to populate those environment variables when running opencode.

Currently, populating variables requires manual shell exports or external tools like direnv.

This friction makes {env:VAR} syntax largely unused in practice, and configs remain filled with hardcoded secrets that can't be committed to version control systems like git.

Proposed Solution

Auto-load .env files from the same directory as opencode.json:

project/
└── .opencode/
    ├── opencode.json         # Git-tracked with {env:VAR} references
    ├── .env.example          # Git-tracked template
    └── .env                  # Git-ignored, auto-loaded

Configuration Example

.env:

SOME_MCP_API_KEY="your-key-here"
ANTHROPIC_API_KEY="your-key-here"

opencode.json:

{
  "mcp": {
    "some-server": {
      "type": "remote",
      "url": "https://api.example.com?key={env:SOME_MCP_API_KEY}"
    }
  },
  "username": "{env:USER}"
}

Implementation

Add support for auto-loading .env files from the same directory as the loaded opencode.json config. Two locations should be supported:

1. Global: ~/.config/opencode/.env (personal defaults, respects $OPENCODE_CONFIG_DIR)
2. Project: ./.opencode/.env (project-specific overrides)

Loading Precedence

1. Global .env (~/.config/opencode/.env)
2. Project .env (./.opencode/.env) - overrides global
3. Process Environment - overrides both
4. Config parsing with {env:VAR} substitution

Opt-In vs Opt-Out

Option A: Opt-In (Recommended)

• Requires OPENCODE_AUTO_LOAD_ENV=true
• Explicit, zero surprise for existing users

Option B: Opt-Out

• Enabled by default when .env exists
• Requires OPENCODE_DISABLE_AUTO_LOAD_ENV=true to disable

Recommendation: Opt-in. Matches OpenCode's transparency principles while still being simple to enable once.

Code Location

Hook into Config.state() in src/config/config.ts after config discovery, before variable substitution:

1. Check enablement flag
2. Load global .env from ~/.config/opencode/.env (respects $OPENCODE_CONFIG_DIR)
3. Load project .env from directory containing opencode.json
4. Log (debug): Loading environment from /path/to/.env
5. Make variables available for {env:VAR} substitution

Benefits

• Teams: Share complete setups without secrets
• Plugins: Document required variables via .env.example
• Security: Credentials stay local, configs in git
• Reproducibility: Clone and run with minimal setup
• Scope-aware: Only loads from .opencode/ directories, not project root

Questions for Community

1. Opt-in (OPENCODE_AUTO_LOAD_ENV=true) or opt-out (default enabled)?
2. Any security concerns with auto-loading .env files?
3. Alternative implementation suggestions?

I'm open to feedback and ready to implement whichever approach is preferred based on the community consensus.