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 embedding OpenCode as a subprocess via opencode serve (e.g. in an Electron app or backend service), the host application
provides all configuration through OPENCODE_CONFIG_CONTENT. However, OpenCode still loads global config files and scans global
directories from ~/.config/opencode/, which can cause unexpected behavior by merging unrelated user-level settings, agents, skills,
and plugins into the intended configuration.
Currently there is no way to skip global config and directory scanning:
OPENCODE_DISABLE_PROJECT_CONFIG only skips project-level config, not global
OPENCODE_CONFIG_CONTENT is additive — it merges on top of global config rather than replacing it
Note: This is related to but different from #20784 (settingSources). That PR provides a granular SDK-level mechanism to control
config sources. This PR takes a simpler approach with a single env var flag, consistent with existing OPENCODE_DISABLE_*
conventions, specifically targeting the embedded opencode serve use case.
Proposed Solution
Add a new environment variable OPENCODE_DISABLE_GLOBAL_CONFIG. When set to 1 or true:
loadGlobal() in config.ts returns an empty config object, skipping all files under ~/.config/opencode/ (config.json,
opencode.json, opencode.jsonc)
ConfigPaths.directories() in paths.ts excludes ~/.config/opencode/ from the returned list, preventing scanning of global
agents, skills, commands, and plugins
Scope
- Skipped:
~/.config/opencode/ config files, agents, skills, commands, plugins
- Not affected: project-level
.opencode/ directories, OPENCODE_CONFIG, OPENCODE_CONFIG_CONTENT, well-known, account, managed
configs
Naming
Follows the existing OPENCODE_DISABLE_* convention (e.g. OPENCODE_DISABLE_PROJECT_CONFIG, OPENCODE_DISABLE_CLAUDE_CODE).
Use Case
// Electron app spawning opencode serve
spawn(binaryPath, ['serve', '--port', '4096'], {
env: {
OPENCODE_DISABLE_GLOBAL_CONFIG: '1',
OPENCODE_DISABLE_CLAUDE_CODE: '1',
OPENCODE_CONFIG_CONTENT: JSON.stringify(myConfig),
},
})
Implementation
Minimal change — 3 files, +15 lines:
- packages/opencode/src/flag/flag.ts: declare flag + dynamic getter
- packages/opencode/src/config/config.ts: early return in loadGlobal()
- packages/opencode/src/config/paths.ts: exclude global directory from ConfigPaths.directories()
PR: #21650
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 embedding OpenCode as a subprocess via
opencode serve(e.g. in an Electron app or backend service), the host applicationprovides all configuration through
OPENCODE_CONFIG_CONTENT. However, OpenCode still loads global config files and scans globaldirectories from
~/.config/opencode/, which can cause unexpected behavior by merging unrelated user-level settings, agents, skills,and plugins into the intended configuration.
Currently there is no way to skip global config and directory scanning:
OPENCODE_DISABLE_PROJECT_CONFIGonly skips project-level config, not globalOPENCODE_CONFIG_CONTENTis additive — it merges on top of global config rather than replacing itNote: This is related to but different from #20784 (
settingSources). That PR provides a granular SDK-level mechanism to controlconfig sources. This PR takes a simpler approach with a single env var flag, consistent with existing
OPENCODE_DISABLE_*conventions, specifically targeting the embedded
opencode serveuse case.Proposed Solution
Add a new environment variable
OPENCODE_DISABLE_GLOBAL_CONFIG. When set to1ortrue:loadGlobal()inconfig.tsreturns an empty config object, skipping all files under~/.config/opencode/(config.json,opencode.json,opencode.jsonc)ConfigPaths.directories()inpaths.tsexcludes~/.config/opencode/from the returned list, preventing scanning of globalagents, skills, commands, and plugins
Scope
~/.config/opencode/config files, agents, skills, commands, plugins.opencode/directories,OPENCODE_CONFIG,OPENCODE_CONFIG_CONTENT, well-known, account, managedconfigs
Naming
Follows the existing
OPENCODE_DISABLE_*convention (e.g.OPENCODE_DISABLE_PROJECT_CONFIG,OPENCODE_DISABLE_CLAUDE_CODE).Use Case
PR: #21650