Skip to content

[FEATURE]: add OPENCODE_DISABLE_GLOBAL_CONFIG flag to skip global config loading #21264

@ZY-Yim

Description

@ZY-Yim

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:

  1. loadGlobal() in config.ts returns an empty config object, skipping all files under ~/.config/opencode/ (config.json,
    opencode.json, opencode.jsonc)
  2. 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

Metadata

Metadata

Assignees

Labels

coreAnything pertaining to core functionality of the application (opencode server stuff)discussionUsed for feature requests, proposals, ideas, etc. Open discussion

Type

No type
No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions