Config

Using the OpenCode JSON config.

You can configure OpenCode using a JSON config file.

Format

OpenCode supports both JSON and JSONC (JSON with Comments) formats.

opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true,
  "server": {
    "port": 4096,
  },
}

Locations

You can place your config in a couple of different locations and they have a different order of precedence.

[!NOTE] Configuration files are merged together, not replaced.

Config sources are loaded in this order (later sources override earlier ones):

Remote config (from .well-known/opencode) - organizational defaults
Global config (~/.config/opencode/opencode.json) - user preferences
Custom config (OPENCODE_CONFIG env var) - custom overrides
Project config (opencode.json in project) - project-specific settings
.opencode directories - agents, commands, plugins
Inline config (OPENCODE_CONFIG_CONTENT env var) - runtime overrides
Managed config files (/Library/Application Support/opencode/ on macOS) - admin-controlled
macOS managed preferences (.mobileconfig via MDM) - highest priority, not user-overridable

Remote

Organizations can provide default configuration via the .well-known/opencode endpoint.

opencode.json

{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true
    }
  }
}

Global

Place your global OpenCode config in ~/.config/opencode/opencode.json.

Per project

Add opencode.json in your project root.

[!TIP] Place project specific config in the root of your project.

Custom path

Specify a custom config file path using the OPENCODE_CONFIG environment variable.

export OPENCODE_CONFIG=/path/to/my/custom-config.json
opencode run "Hello world"

Custom directory

Specify a custom config directory using the OPENCODE_CONFIG_DIR environment variable.

export OPENCODE_CONFIG_DIR=/path/to/my/config-directory
opencode run "Hello world"

Managed settings

Organizations can enforce configuration that users cannot override.

Platform	Path
macOS	`/Library/Application Support/opencode/`
Linux	`/etc/opencode/`
Windows	`%ProgramData%\opencode`

Schema

The server/runtime config schema is defined in opencode.ai/config.json.

Your editor should be able to validate and autocomplete based on the schema.

TUI

Use a dedicated tui.json (or tui.jsonc) file for TUI-specific settings.

tui.json

{
  "$schema": "https://opencode.ai/tui.json",
  "scroll_speed": 3,
  "diff_style": "auto",
  "mouse": true,
  "attention": {
    "enabled": true,
    "notifications": true,
    "sound": true,
    "volume": 0.4
  }
}

Server

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true,
    "mdnsDomain": "myproject.local",
    "cors": ["http://localhost:5173"]
  }
}

Available options:

port - Port to listen on
hostname - Hostname to listen on; defaults to 0.0.0.0 when mdns is enabled
mdns - Enable mDNS service discovery so other devices on the LAN can find the OpenCode server
mdnsDomain - Custom mDNS domain name; defaults to opencode.local
cors - Additional allowed CORS origins; values must be full origins (scheme + host + optional port)

Shell

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "shell": "pwsh"
}

Tools

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": false,
    "bash": false
  }
}

Models

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {},
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

Provider options:

timeout - Request timeout in milliseconds; defaults to 300000
chunkTimeout - Timeout between streamed response chunks
setCacheKey - Ensures a cache key is always set for the given provider

Policies

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "experimental": {
    "policies": [
      {
        "effect": "deny",
        "action": "provider.use",
        "resource": "openai"
      }
    ]
  }
}

Image attachments

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "attachment": {
    "image": {
      "auto_resize": true,
      "max_width": 2000,
      "max_height": 2000,
      "max_base64_bytes": 5242880
    }
  }
}

Themes

tui.json

{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "tokyonight"
}

Agents

opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "You are a code reviewer.",
      "tools": {
        "write": false,
        "edit": false,
      },
    },
  },
}

Default agent

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "default_agent": "plan"
}

Subagent depth

You can control how deeply subagents can invoke other subagents using the subagent_depth option:

{
  "$schema": "https://opencode.ai/config.json",
  "subagent_depth": 2
}

The default is 1, which allows primary agents to launch subagents but prevents those subagents from launching additional subagents. Set it to 2 to allow one additional level of nested subagents, or 0 to prevent all subagent launches.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "share": "manual"
}

"manual" - Allow sharing manually via command (default)
"auto" - Automatically share new conversations
"disabled" - Disable sharing entirely

Commands

opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "template": "Run the full test suite with coverage report.",
      "description": "Run tests with coverage",
      "agent": "build",
      "model": "anthropic/claude-haiku-4-5",
    },
  },
}

Keybinds

tui.json

{
  "$schema": "https://opencode.ai/tui.json",
  "keybinds": {
    "command_list": "ctrl+p"
  }
}

Snapshot

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "snapshot": false
}

Autoupdate

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "autoupdate": false
}

false - Disable automatic updates
"notify" - Don’t auto-update, but notify when a new version is available

Formatters

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "formatter": true
}

LSP Servers

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": true
}

Permissions

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

Compaction

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "compaction": {
    "auto": true,
    "prune": false,
    "reserved": 10000
  }
}

auto - Compact automatically when the context is full (default true)
prune - Remove old tool outputs to save tokens (default false)
reserved - Token buffer reserved during compaction

Watcher

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "watcher": {
    "ignore": ["node_modules/**", "dist/**", ".git/**"]
  }
}

MCP servers

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {}
}

Plugins

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-helicone-session", "@my-org/custom-plugin"]
}

Instructions

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
}

Disabled providers

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "disabled_providers": ["openai", "gemini"]
}

Enabled providers

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "enabled_providers": ["anthropic", "openai"]
}

[!NOTE] disabled_providers takes precedence over enabled_providers

Experimental

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "experimental": {}
}

Variables

Env vars

Use {env:VARIABLE_NAME} to reference environment variables:

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "model": "{env:OPENCODE_MODEL}",
  "provider": {
    "anthropic": {
      "models": {},
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    }
  }
}

Files

Use {file:path/to/file} to reference file contents:

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["./custom-instructions.md"],
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

References — mount local directories and Git repositories outside the project

Config

Format

Locations

Remote

Global

Per project

Custom path

Custom directory

Managed settings

Schema

TUI

Server

Shell

Tools

Models

Policies

Image attachments

Themes

Agents

Default agent

Subagent depth

Sharing

Commands

Keybinds

Snapshot

Autoupdate

Formatters

LSP Servers

Permissions

Compaction

Watcher

MCP servers

Plugins

Instructions

Disabled providers

Enabled providers

Experimental

Variables

Env vars

Files

Related