[FEATURE]: Auto-load .env files in scoped directories for {env:VAR} substitution

[mcking-07]

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.

[github-actions]

This issue might be a duplicate of existing issues. Please check:

• add ability to load secrets from external command or environment variables in the config file #231: add ability to load secrets from external command or environment variables in the config file (earliest related feature request from 2020)
• [FEATURE]: {env:MY_VAR} support in agent yaml #5054: {env:MY_VAR} support in agent yaml (shows demand for env var substitution in configs)
• {env:...} variable substitution inconsistently fails for specific MCP server URLs #5299: {env:...} variable substitution inconsistently fails for specific MCP server URLs (existing issue with {env:VAR} syntax)
• How to make OpenCode load environment variables from a file when executing commands in skills #9334: How to make OpenCode load environment variables from a file when executing commands in skills (user asking for .env file loading)

Feel free to ignore if your implementation differs from these existing proposals.

[vpcano]

I think desktop/web app would benefit from this, because on the TUI you can at least source a .env file manually or use dotenv, but on the desktop application there is no way to load env vars from a project.

[mcking-07]

@vpcano Good point on the desktop gap. This is straightforward to implement since {env:VAR} substitution already exists, just need to load .env files before config parsing. Given the 4 related issues flagged, seems like there's clear demand for this. Thoughts on the opt-in vs opt-out approach?

[AlexBlack772]

I support several projects, and each one has its own .env settings. When I switch between projects, I have to close the terminal session to clear the variables, then load the .env file and then run opencode

Automatic loading of .env from the current directory would be very useful

[github-actions]

To stay organized issues are automatically closed after 60 days of no activity. If the issue is still relevant please open a new one.