Opencode Config

OpenCode Configuration

📚 Official Docs: For the latest information, always refer to the official documentation: https://opencode.ai/docs/config/

OpenCode uses JSON-based configuration files to control runtime behavior, TUI appearance, server settings, tool permissions, agent definitions, and provider connections. This skill covers every aspect of configuration: file format, locations, precedence, merging, all available fields, TUI config, variable substitution, enterprise managed settings, environment variables, and troubleshooting.

Table of Contents

• Format
• Config Locations & Precedence
• Config Merging Behavior
• All Config Fields
• TUI Config (tui.json)
• Variable Substitution
• Managed Settings (Enterprise)
• Provider-Specific Options
• Environment Variables
• Debugging & Verification
• Troubleshooting

Format

OpenCode supports both JSON and JSONC (JSON with Comments) formats for all configuration files.

Schema

Every config file should include a $schema field for editor validation and autocomplete:

• Server/runtime config: "$schema": "https://opencode.ai/config.json"
• TUI config: "$schema": "https://opencode.ai/tui.json"

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

Schemas enable autocompletion in VS Code, JetBrains editors, and other JSON-aware editors. Omitting the schema is valid but not recommended.

Config Locations & Precedence

Configuration files are merged together, not replaced. Settings from multiple locations are combined. Later sources override earlier ones only for conflicting keys. Non-conflicting settings from all configs are preserved.

Precedence Order (lowest to highest)

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

For example, if your global config sets autoupdate: true and your project config sets model: "anthropic/claude-sonnet-4-5", the final configuration will include both settings. If both set the same key, the project config wins.

Remote Config

Organizations can provide default configuration via the .well-known/opencode endpoint. This is fetched automatically when you authenticate with a provider that supports it.

Remote config is loaded first, serving as the base layer. All other config sources (global, project, managed) can override these defaults.

// Remote config from .well-known/opencode
{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": false
    }
  }
}

Override in your local config:

// opencode.json (project or global)
{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true
    }
  }
}

Global Config

Place your global OpenCode config in ~/.config/opencode/opencode.json. Use global config for user-wide server/runtime preferences like providers, models, and permissions.

For TUI-specific settings, use ~/.config/opencode/tui.json.

Global config overrides remote organizational defaults.

Project Config

Add opencode.json in your project root. Project config has the highest precedence among standard config files — it overrides both global and remote configs.

When OpenCode starts up, it first looks for a config file in the current directory, then traverses up to the nearest Git directory. This file is safe to check into Git and uses the same schema as the global one.

Custom Config Path (OPENCODE_CONFIG)

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 config is loaded between global and project configs in the precedence order.

Custom Config Directory (OPENCODE_CONFIG_DIR)

Specify a custom config directory using the OPENCODE_CONFIG_DIR environment variable. This directory will be searched for agents, commands, modes, and plugins just like the standard .opencode directory:

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

The custom directory is loaded after the global config and .opencode directories, so it can override their settings.

.opencode Directories

The .opencode and ~/.config/opencode directories use plural names for subdirectories: agents/, commands/, modes/, plugins/, skills/, tools/, and themes/. Singular names (e.g., agent/) are also supported for backwards compatibility.

Inline Config (OPENCODE_CONFIG_CONTENT)

Pass configuration directly as a JSON string via the OPENCODE_CONFIG_CONTENT environment variable. Useful for runtime overrides without touching files:

export OPENCODE_CONFIG_CONTENT='{"model": "anthropic/claude-sonnet-4-5"}'
opencode run "Hello world"

Config Merging Behavior

Configs are merged, not replaced. When two config sources define the same key, the merge behavior depends on the value type:

• Scalar values (strings, numbers, booleans): later source wins
• Objects: recursively merged; later source keys override earlier ones
• Arrays: later source replaces the entire array (not appended)

Example flow:

1. Global sets autoupdate: true
2. Project sets model: "anthropic/claude-sonnet-4-5"
3. Final config: both autoupdate: true AND model: "anthropic/claude-sonnet-4-5" are present

Example with arrays (important caveat):

1. Global sets instructions: ["CONTRIBUTING.md"]
2. Project sets instructions: ["docs/guidelines.md"]
3. Final config: instructions: ["docs/guidelines.md"] — the global array is replaced, not merged

All Config Fields

$schema

JSON Schema URL for editor validation and autocomplete.

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

model

The primary LLM model used for conversations. Format: provider/model-name.

{
  "model": "anthropic/claude-sonnet-4-5"
}

small_model

A separate model for lightweight tasks like title generation and compaction summaries. By default, OpenCode tries to use a cheaper model from your provider, falling back to the main model.

{
  "small_model": "anthropic/claude-haiku-4-5"
}

provider

Provider configuration with API keys, endpoints, and options. Each key is a provider ID (e.g., anthropic, openai, amazon-bedrock, ollama).

{
  "provider": {
    "anthropic": {
      "models": {},
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}",
        "timeout": 600000,
        "chunkTimeout": 30000,
        "setCacheKey": true
      }
    }
  }
}

Provider options:

Custom provider (npm):

Use any OpenAI-compatible provider by specifying an npm package:

{
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "llama2": {
          "name": "Llama 2"
        }
      }
    }
  }
}

plugin

Load plugins from npm packages or local paths:

{
  "plugin": ["opencode-helicone-session", "@my-org/custom-plugin"]
}

Plugins can also be placed in .opencode/plugins/ or ~/.config/opencode/plugins/ as JavaScript/TypeScript files, which are loaded automatically at startup.

mcp

MCP (Model Context Protocol) server configurations for adding external tools:

{
  "mcp": {
    "my-local-server": {
      "type": "local",
      "command": ["npx", "-y", "@my-org/mcp-server"],
      "enabled": true,
      "environment": {
        "MY_ENV_VAR": "value"
      }
    },
    "my-remote-server": {
      "type": "remote",
      "url": "https://mcp.example.com",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:MY_API_KEY}"
      }
    }
  }
}

Local MCP options:

Remote MCP options:

Remote MCP OAuth options:

tools

Enable/disable tools globally. Set a tool to false to disable it, or true to enable it:

{
  "tools": {
    "write": false,
    "bash": false
  }
}

Glob patterns are supported for MCP tool names:

{
  "tools": {
    "my-mcp*": false
  }
}

As of v1.1.1, the legacy tools boolean config is deprecated and has been merged into permission.

permission

Granular permission rules for tool execution. Controls whether actions require user approval, are auto-approved, or are blocked.

{
  "permission": {
    "*": "ask",
    "bash": "ask",
    "edit": "allow",
    "bash": {
      "*": "ask",
      "git *": "allow",
      "rm *": "deny"
    },
    "edit": {
      "*": "deny",
      "packages/web/src/*.mdx": "allow"
    }
  }
}

Permission values:

Available permission keys:

Granular rules (object syntax):

Rules are evaluated by pattern match, with the last matching rule winning. Use "*" as catch-all first, then specific patterns after.

• * matches zero or more of any character
• ? matches exactly one character
• All other characters match literally

Home directory expansion:

Use ~ or $HOME at the start of a pattern to reference your home directory:

• ~/projects/* → /Users/username/projects/*
• $HOME/projects/* → /Users/username/projects/*

External directory access:

Use external_directory to allow tool calls that touch paths outside the working directory:

{
  "permission": {
    "external_directory": {
      "~/projects/personal/**": "allow"
    }
  }
}

Defaults (if nothing is specified):

• Most permissions default to "allow"
• doom_loop and external_directory default to "ask"
• read defaults to "allow" but .env files are denied:

{
  "permission": {
    "read": {
      "*": "allow",
      "*.env": "deny",
      "*.env.*": "deny",
      "*.env.example": "allow"
    }
  }
}

What "Ask" does:

When OpenCode prompts for approval, three outcomes are offered:

• once — approve just this request
• always — approve future requests matching suggested patterns (rest of session)
• reject — deny the request

Agent-level permissions:

Permissions can be overridden per agent. Agent permissions merge with global config, and agent rules take precedence:

{
  "permission": {
    "bash": {
      "*": "ask",
      "git *": "allow"
    }
  },
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "*": "ask",
          "git commit *": "ask",
          "git push *": "deny"
        }
      }
    }
  }
}

agent

Define specialized agents for specific tasks. Each agent can have its own model, prompt, tools, permissions, and other settings.

{
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        "write": false,
        "edit": false
      },
      "permission": {
        "edit": "deny"
      }
    }
  }
}

Agents can also be defined as markdown files in ~/.config/opencode/agents/ or .opencode/agents/:

---
description: Code review without edits
mode: subagent
permission:
  edit: deny
  bash: ask
  webfetch: deny
---
Only analyze code and suggest changes.

default_agent

Set the default agent used when none is explicitly specified. Must be a primary agent (not a subagent). Can be a built-in agent ("build", "plan") or a custom agent. Falls back to "build" with a warning if the specified agent doesn't exist or is a subagent.

{
  "default_agent": "plan"
}

This setting applies across all interfaces: TUI, CLI (opencode run), desktop app, and GitHub Action.

share

Configure the conversation sharing feature:

{
  "share": "manual"
}

command

Define custom slash commands for repetitive tasks:

{
  "command": {
    "test": {
      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
      "description": "Run tests with coverage",
      "agent": "build",
      "model": "anthropic/claude-haiku-4-5"
    },
    "component": {
      "template": "Create a new React component named $ARGUMENTS with TypeScript support.\nInclude proper typing and basic structure.",
      "description": "Create a new component"
    }
  }
}

Commands can also be defined as markdown files in ~/.config/opencode/commands/ or .opencode/commands/.

formatter

Enable and configure code formatters. Omit to keep formatters disabled.

{
  "formatter": true
}

Use an object to keep built-ins enabled while configuring overrides or custom formatters:

{
  "formatter": {
    "prettier": {
      "disabled": true
    },
    "custom-prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "environment": {
        "NODE_ENV": "development"
      },
      "extensions": [".js", ".ts", ".jsx", ".tsx"]
    }
  }
}

lsp

Enable and configure LSP (Language Server Protocol) servers. Omit to keep LSP disabled.

{
  "lsp": true
}

Use an object to keep built-ins enabled while configuring overrides:

{
  "lsp": {
    "typescript": {
      "disabled": true
    }
  }
}

snapshot

OpenCode uses snapshots to track file changes during agent operations, enabling undo/revert within a session. Snapshots are enabled by default.

For large repositories or projects with many submodules, disable snapshots to avoid slow indexing and significant disk usage:

{
  "snapshot": false
}

Disabling snapshots means changes made by the agent cannot be rolled back through the UI.

autoupdate

OpenCode automatically downloads new updates on startup.

{
  "autoupdate": false
}

instructions

Point to instruction/rule files using paths and glob patterns. These files are loaded as system instructions for the LLM:

{
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
}

disabled_providers

Disable specific providers that would otherwise be loaded automatically:

{
  "disabled_providers": ["openai", "gemini"]
}

When a provider is disabled:

• It won't be loaded even if environment variables are set
• It won't be loaded even if API keys are configured via /connect
• The provider's models won't appear in the model selection list

enabled_providers

Allowlist specific providers. When set, only the specified providers will be enabled and all others will be ignored:

{
  "enabled_providers": ["anthropic", "openai"]
}

disabled_providers takes priority over enabled_providers. If a provider appears in both, it is disabled.

experimental

Options under active development. Not stable — may change or be removed without notice.

{
  "experimental": {
    "policies": [
      {
        "effect": "deny",
        "action": "provider.use",
        "resource": "openai"
      }
    ]
  }
}

Policies allow or deny OpenCode actions on configured resources. Currently, policies can control which providers OpenCode may use.

attachment.image

Configure image attachment limits. OpenCode normalizes images before sending to the model. By default, images are resized when they exceed 2000x2000 pixels or 5242880 base64 bytes.

{
  "attachment": {
    "image": {
      "auto_resize": true,
      "max_width": 2000,
      "max_height": 2000,
      "max_base64_bytes": 5242880
    }
  }
}

If an image still cannot fit after resizing, OpenCode omits oversized tool-result images or fails oversized user-provided images with an image size error.

compaction

Control context compaction behavior:

{
  "compaction": {
    "auto": true,
    "prune": true,
    "reserved": 10000
  }
}

watcher

Configure file watcher ignore patterns:

{
  "watcher": {
    "ignore": ["node_modules/**", "dist/**", ".git/**"]
  }
}

Patterns follow glob syntax. Use this to exclude noisy directories from file watching.

shell

Configure the shell used for the interactive terminal and agent tool calls:

{
  "shell": "pwsh"
}

If not specified, OpenCode automatically discovers a sensible default based on your OS (pwsh or cmd.exe on Windows, /bin/zsh or /bin/bash on macOS/Linux). You can provide an absolute path or a short name.

server

Configure server settings for opencode serve and opencode web commands:

{
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true,
    "mdnsDomain": "myproject.local",
    "cors": ["http://localhost:5173"]
  }
}

TUI Config (tui.json)

Use a dedicated tui.json (or tui.jsonc) file for TUI-specific settings. This is separate from opencode.json, which configures server/runtime behavior.

{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "tokyonight",
  "leader_timeout": 2000,
  "scroll_speed": 3,
  "scroll_acceleration": {
    "enabled": false
  },
  "diff_style": "auto",
  "mouse": true,
  "keybinds": {
    "leader": "ctrl+x",
    "command_list": "ctrl+p"
  },
  "attention": {
    "enabled": true,
    "notifications": true,
    "sound": true,
    "volume": 0.4,
    "sound_pack": "opencode.default",
    "sounds": {
      "error": "./sounds/error.mp3"
    }
  }
}

Use OPENCODE_TUI_CONFIG to point to a custom TUI config file.

Legacy theme, keybinds, and tui keys in opencode.json are deprecated and automatically migrated when possible.

TUI Options

Keybinds

All customizable keybinds with their defaults:

{
  "keybinds": {
    "leader": "ctrl+x",
    "app_exit": "ctrl+c,ctrl+d,<leader>q",
    "app_debug": "none",
    "app_console": "none",
    "app_heap_snapshot": "none",
    "app_toggle_animations": "none",
    "app_toggle_file_context": "none",
    "app_toggle_diffwrap": "none",
    "app_toggle_paste_summary": "none",
    "app_toggle_session_directory_filter": "none",
    "command_list": "ctrl+p",
    "help_show": "none",
    "docs_open": "none",
    "editor_open": "<leader>e",
    "theme_list": "<leader>t",
    "theme_switch_mode": "none",
    "theme_mode_lock": "none",
    "sidebar_toggle": "<leader>b",
    "scrollbar_toggle": "none",
    "status_view": "<leader>s",
    "session_export": "<leader>x",
    "session_copy": "none",
    "session_new": "<leader>n",
    "session_list": "<leader>l",
    "session_timeline": "<leader>g",
    "session_fork": "none",
    "session_rename": "ctrl+r",
    "session_delete": "ctrl+d",
    "session_share": "none",
    "session_unshare": "none",
    "session_interrupt": "escape",
    "session_compact": "<leader>c",
    "session_toggle_timestamps": "none",
    "session_toggle_generic_tool_output": "none",
    "session_child_first": "<leader>down",
    "session_child_cycle": "right",
    "session_child_cycle_reverse": "left",
    "session_parent": "up",
    "stash_delete": "ctrl+d",
    "model_provider_list": "ctrl+a",
    "model_favorite_toggle": "ctrl+f",
    "model_list": "<leader>m",
    "model_cycle_recent": "f2",
    "model_cycle_recent_reverse": "shift+f2",
    "model_cycle_favorite": "none",
    "model_cycle_favorite_reverse": "none",
    "mcp_list": "none",
    "provider_connect": "none",
    "console_org_switch": "none",
    "agent_list": "<leader>a",
    "agent_cycle": "tab",
    "agent_cycle_reverse": "shift+tab",
    "variant_cycle": "ctrl+t",
    "variant_list": "none",
    "messages_page_up": "pageup,ctrl+alt+b",
    "messages_page_down": "pagedown,ctrl+alt+f",
    "messages_line_up": "ctrl+alt+y",
    "messages_line_down": "ctrl+alt+e",
    "messages_half_page_up": "ctrl+alt+u",
    "messages_half_page_down": "ctrl+alt+d",
    "messages_first": "ctrl+g,home",
    "messages_last": "ctrl+alt+g,end",
    "messages_next": "none",
    "messages_previous": "none",
    "messages_last_user": "none",
    "messages_copy": "<leader>y",
    "messages_undo": "<leader>u",
    "messages_redo": "<leader>r",
    "messages_toggle_conceal": "<leader>h",
    "tool_details": "none",
    "display_thinking": "none",
    "prompt_submit": "none",
    "prompt_editor_context_clear": "none",
    "prompt_skills": "none",
    "prompt_stash": "none",
    "prompt_stash_pop": "none",
    "prompt_stash_list": "none",
    "workspace_set": "none",
    "input_clear": "ctrl+c",
    "input_paste": {
      "key": "ctrl+v",
      "preventDefault": false
    },
    "input_submit": "return",
    "input_newline": "shift+return,ctrl+return,alt+return,ctrl+j",
    "input_move_left": "left,ctrl+b",
    "input_move_right": "right,ctrl+f",
    "input_move_up": "up",
    "input_move_down": "down",
    "input_select_left": "shift+left",
    "input_select_right": "shift+right",
    "input_select_up": "shift+up",
    "input_select_down": "shift+down",
    "input_line_home": "ctrl+a",
    "input_line_end": "ctrl+e",
    "input_select_line_home": "ctrl+shift+a",
    "input_select_line_end": "ctrl+shift+e",
    "input_visual_line_home": "alt+a",
    "input_visual_line_end": "alt+e",
    "input_select_visual_line_home": "alt+shift+a",
    "input_select_visual_line_end": "alt+shift+e",
    "input_buffer_home": "home",
    "input_buffer_end": "end",
    "input_select_buffer_home": "shift+home",
    "input_select_buffer_end": "shift+end",
    "input_delete_line": "ctrl+shift+d",
    "input_delete_to_line_end": "ctrl+k",
    "input_delete_to_line_start": "ctrl+u",
    "input_backspace": "backspace,shift+backspace",
    "input_delete": "ctrl+d,delete,shift+delete",
    "input_undo": "ctrl+-,super+z",
    "input_redo": "ctrl+.,super+shift+z",
    "input_word_forward": "alt+f,alt+right,ctrl+right",
    "input_word_backward": "alt+b,alt+left,ctrl+left",
    "input_select_word_forward": "alt+shift+f,alt+shift+right",
    "input_select_word_backward": "alt+shift+b,alt+shift+left",
    "input_delete_word_forward": "alt+d,alt+delete,ctrl+delete",
    "input_delete_word_backward": "ctrl+w,ctrl+backspace,alt+backspace",
    "input_select_all": "super+a",
    "history_previous": "up",
    "history_next": "down",
    "dialog.select.prev": "up,ctrl+p",
    "dialog.select.next": "down,ctrl+n",
    "dialog.select.page_up": "pageup",
    "dialog.select.page_down": "pagedown",
    "dialog.select.home": "home",
    "dialog.select.end": "end",
    "dialog.select.submit": "return",
    "dialog.prompt.submit": "return",
    "dialog.mcp.toggle": "space",
    "prompt.autocomplete.prev": "up,ctrl+p",
    "prompt.autocomplete.next": "down,ctrl+n",
    "prompt.autocomplete.hide": "escape",
    "prompt.autocomplete.select": "return",
    "prompt.autocomplete.complete": "tab",
    "permission.prompt.fullscreen": "ctrl+f",
    "plugins.toggle": "space",
    "dialog.plugins.install": "shift+i",
    "terminal_suspend": "ctrl+z",
    "terminal_title_toggle": "none",
    "tips_toggle": "<leader>h",
    "plugin_manager": "none",
    "plugin_install": "none",
    "which_key_toggle": "ctrl+alt+k",
    "which_key_layout_toggle": "ctrl+alt+shift+k",
    "which_key_pending_toggle": "ctrl+alt+shift+p",
    "which_key_group_previous": "ctrl+alt+left,ctrl+alt+[",
    "which_key_group_next": "ctrl+alt+right,ctrl+alt+]",
    "which_key_scroll_up": "ctrl+alt+up,ctrl+alt+p",
    "which_key_scroll_down": "ctrl+alt+down,ctrl+alt+n",
    "which_key_page_up": "ctrl+alt+pageup",
    "which_key_page_down": "ctrl+alt+pagedown",
    "which_key_home": "ctrl+alt+home",
    "which_key_end": "ctrl+alt+end"
  }
}

Windows defaults differ for:

• input_undo defaults to ctrl+z,ctrl+-,super+z (adds ctrl+z because Windows terminals don't support POSIX suspend)
• terminal_suspend is forced to none (native Windows terminals don't support POSIX suspend)

Binding values:

A string can contain one shortcut or multiple comma-separated shortcuts. Use an array for multiple shortcuts:

{
  "keybinds": {
    "messages_copy": ["<leader>y", "ctrl+shift+c"]
  }
}

For advanced cases, use an object with key, event, preventDefault, or fallthrough:

{
  "keybinds": {
    "input_paste": {
      "key": "ctrl+v",
      "preventDefault": false
    }
  }
}

Disable a keybind by setting it to "none" or false:

{
  "keybinds": {
    "session_compact": "none"
  }
}

Attention (Notifications & Sound)

The attention section controls TUI desktop notifications and sounds. Disabled by default.

{
  "attention": {
    "enabled": true,
    "notifications": true,
    "sound": true,
    "volume": 0.4,
    "sound_pack": "opencode.default",
    "sounds": {
      "default": "./sounds/default.mp3",
      "question": "./sounds/question.mp3",
      "permission": "./sounds/permission.mp3",
      "error": "./sounds/error.mp3",
      "done": "./sounds/done.mp3",
      "subagent_done": "./sounds/subagent_done.mp3"
    }
  }
}

Built-in events play sounds when triggered, and non-subagent events request desktop notifications only when the terminal is blurred.

Variable Substitution

Use variable substitution in config files to reference environment variables and file contents.

Environment Variables

Use {env:VARIABLE_NAME} to substitute environment variables:

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

If the environment variable is not set, it is replaced with an empty string.

File Contents

Use {file:path/to/file} to substitute the contents of a file:

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

File paths can be:

• Relative to the config file directory
• Absolute paths starting with / or ~

Useful for:

• Keeping sensitive data like API keys in separate files
• Including large instruction files without cluttering your config
• Sharing common configuration snippets across multiple config files

Managed Settings (Enterprise)

Organizations can enforce configuration that users cannot override. Managed settings are loaded at the highest priority tier (tier 7-8), overriding everything else.

File-based

Drop an opencode.json or opencode.jsonc file in the system managed config directory:

These directories require admin/root access to write, so users cannot modify them.

macOS Managed Preferences (.mobileconfig via MDM)

On macOS, OpenCode reads managed preferences from the ai.opencode.managed preference domain. Deploy a .mobileconfig via MDM (Jamf, Kandji, FleetDM) and the settings are enforced automatically.

OpenCode checks these paths:

1. /Library/Managed Preferences/<user>/ai.opencode.managed.plist
2. /Library/Managed Preferences/ai.opencode.managed.plist

The plist keys map directly to opencode.json fields. MDM metadata keys (PayloadUUID, PayloadType, etc.) are stripped automatically.

Creating a .mobileconfig:

Use the ai.opencode.managed PayloadType. The OpenCode config keys go directly in the payload dict:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>PayloadContent</key>
  <array>
    <dict>
      <key>PayloadType</key>
      <string>ai.opencode.managed</string>
      <key>PayloadIdentifier</key>
      <string>com.example.opencode.config</string>
      <key>PayloadUUID</key>
      <string>GENERATE-YOUR-OWN-UUID</string>
      <key>PayloadVersion</key>
      <integer>1</integer>
      <key>share</key>
      <string>disabled</string>
      <key>server</key>
      <dict>
        <key>hostname</key>
        <string>127.0.0.1</string>
      </dict>
      <key>permission</key>
      <dict>
        <key>*</key>
        <string>ask</string>
        <key>bash</key>
        <dict>
          <key>*</key>
          <string>ask</string>
          <key>rm -rf *</key>
          <string>deny</string>
        </dict>
      </dict>
    </dict>
  </array>
  <key>PayloadType</key>
  <string>Configuration</string>
  <key>PayloadIdentifier</key>
  <string>com.example.opencode</string>
  <key>PayloadUUID</key>
  <string>GENERATE-YOUR-OWN-UUID</string>
  <key>PayloadVersion</key>
  <integer>1</integer>
</dict>
</plist>

Generate unique UUIDs with uuidgen. Customize the settings to match your organization's requirements.

Deploying via MDM:

• Jamf Pro: Computers > Configuration Profiles > Upload > scope to target devices or smart groups
• Kandji: Custom Profiles > upload the .mobileconfig
• FleetDM: Add the .mobileconfig to your gitops repo under mdm.macos_settings.custom_settings and run fleetctl apply

Verifying on a device:

opencode debug config

All managed preference keys appear in the resolved config and cannot be overridden by user or project configuration.

Provider-Specific Options

Amazon Bedrock

Amazon Bedrock supports AWS-specific configuration:

{
  "provider": {
    "amazon-bedrock": {
      "options": {
        "region": "us-east-1",
        "profile": "my-aws-profile",
        "endpoint": "https://bedrock-runtime.us-east-1.vpce-xxxxx.amazonaws.com"
      }
    }
  }
}

Authentication methods:

• AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY: IAM user access keys
• AWS_PROFILE: Named profiles from ~/.aws/credentials
• AWS_BEARER_TOKEN_BEDROCK: Long-term API keys from the Bedrock console
• AWS_WEB_IDENTITY_TOKEN_FILE / AWS_ROLE_ARN: EKS IRSA (IAM Roles for Service Accounts)

Authentication precedence:

1. Bearer Token — AWS_BEARER_TOKEN_BEDROCK environment variable or token from /connect command
2. AWS Credential Chain — Profile, access keys, shared credentials, IAM roles, Web Identity Tokens (EKS IRSA), instance metadata

Bearer tokens take precedence over all AWS credential methods including configured profiles.

Custom inference profiles:

{
  "provider": {
    "amazon-bedrock": {
      "models": {
        "anthropic-claude-sonnet-4.5": {
          "id": "arn:aws:bedrock:us-east-1:xxx:application-inference-profile/yyy"
        }
      }
    }
  }
}

Generic Provider Options (All Providers)

Environment Variables

…(truncated)