OpenCode opencode.json settings

Schema URL for editor validation/autocomplete.

https://opencode.ai/config.json

Default model in provider/model format.

string

Separate model for lightweight tasks like title generation; defaults to a cheaper provider model or falls back to the main model.

string

Provider configuration, including options and models.

object

Request timeout in ms; set false to disable.

number or false; default 300000

Timeout in ms to wait for response headers; set false to disable.

number or false; default 300000

Timeout in ms between streamed response chunks; request aborts if exceeded. Set false to disable.

number or false; default 900000

Ensures a cache key is always set for the designated provider.

boolean

Custom base URL for a provider, useful for proxies or custom endpoints.

string

Optional API key for a provider if not using auth; supports {env:...} and {file:...}.

string

Custom headers sent with each request.

object

Amazon Bedrock AWS region.

string; defaults to AWS_REGION or us-east-1

Amazon Bedrock named AWS profile.

string; defaults to AWS_PROFILE

Amazon Bedrock custom endpoint URL for VPC endpoints; alias for baseURL and takes precedence.

string

Hides the listed model IDs from the /models picker.

array of model IDs

Keeps only the listed model IDs in the /models picker.

array of model IDs

AI SDK package to use, e.g. @ai-sdk/openai-compatible for /v1/chat/completions or @ai-sdk/openai for /v1/responses.

string

Display name for a custom provider in the UI.

string

Available models for a provider, keyed by model ID.

object

Maximum input tokens the model accepts.

number

Maximum tokens the model can generate.

number

Global model options passed to the provider (e.g. reasoningEffort, thinking).

object

Custom or overridden model variants; a variant can be disabled with disabled: true.

object

Shell used for the interactive terminal and compatible agent tool calls; absolute path or short name.

string; auto-detected by OS

Enables or disables tools the LLM can use (legacy, deprecated in favor of permission); supports wildcards.

object of tool -> boolean

Server settings for opencode serve and opencode web.

object

Port to listen on.

number

Hostname to listen on; defaults to 0.0.0.0 when mdns is enabled and no hostname is set.

string

Enables mDNS service discovery.

boolean

Custom mDNS domain name.

string; default opencode.local

Additional full origins allowed for CORS.

array of origins

Options under active development; not stable.

object

Ordered policy statements allowing or denying actions on resources (currently provider.use).

array

Policy effect.

allow or deny

Operation controlled by the policy.

provider.use

Resource ID or wildcard pattern (* and ?) the statement applies to.

string

Resizes images exceeding limits before provider requests; false rejects oversized images.

boolean; default true

Maximum image width in pixels before resizing or rejection.

number; default 2000

Maximum image height in pixels before resizing or rejection.

number; default 2000

Maximum base64-encoded image payload size.

number; default 5242880

Configures built-in or custom agents by name.

object

Default primary agent when none is specified; falls back to build with a warning if missing or a subagent.

string; e.g. build or plan

How deeply subagents can invoke other subagents; 0 prevents all subagent launches.

number; default 1

Custom commands for repetitive tasks.

object

Enables snapshots used to undo/revert agent file changes; disabling avoids slow indexing in large repos.

boolean; default true

Automatic update downloads at startup; notify only shows when a new version is available (not for package-manager installs).

true, false, or "notify"

Enables and configures code formatters; omit to keep formatters disabled.

true, false, or object

Enables and configures LSP servers; omit to keep LSP disabled.

true, false, or object

Controls whether actions run automatically, prompt, or are blocked; can be a single action or per-tool rules.

allow, ask, deny, or object

Automatically compacts the session when context is full.

boolean; default true

Removes old tool outputs to save tokens.

boolean; default false

Token buffer for compaction to avoid overflow during compaction.

number

Glob patterns ignored by the file watcher; common dependency, VCS, build and cache dirs are ignored automatically.

array of globs

MCP server definitions keyed by name.

object

npm plugins to load.

array of package names

Paths, glob patterns or remote URLs of instruction files combined with AGENTS.md; remote URLs use a 5 second timeout.

array of strings

Provider IDs that won't be loaded even if credentials exist; takes priority over enabled_providers.

array of provider IDs

Allowlist of provider IDs; all others are ignored.

array of provider IDs

Local directories or Git repositories made available as project references by alias.

object

Local reference directory (relative to config, absolute, or ~).

string

Git URL, host/path, or GitHub owner/repo reference, materialized in the local repository cache.

string

Optional Git branch or ref; defaults to the repository's default branch.

string

Guidance describing when agents should use the reference; references with descriptions are included in agent context.

string

Hides the reference from TUI @ autocomplete only.

boolean

Brief description of what the agent does and when to use it; required.

string

Randomness of responses; defaults are model-specific (typically 0, 0.55 for Qwen).

number, typically 0.0-1.0

Maximum agentic iterations before the agent must respond with text only (legacy maxSteps is deprecated).

number

Set true to disable the agent.

boolean

Custom system prompt file, relative to the config file.

string, e.g. {file:./prompts/build.txt}

Overrides the model for this agent in provider/model-id format.

string

Deprecated per-agent tool toggles; true equals {"*": "allow"} and false equals {"*": "deny"}.

object

Per-agent permission overrides merged with global config.

object

How the agent can be used.

primary, subagent, or all; default all

Hides a subagent from @ autocomplete; it can still be invoked via the Task tool.

boolean

Glob rules controlling which subagents an agent can invoke via the Task tool; last matching rule wins.

object of glob -> allow/ask/deny

Agent color in the UI.

hex color or primary, secondary, accent, success, warning, error, info

Response diversity, alternative to temperature.

number 0.0-1.0

Prompt sent to the LLM when the command runs; supports $ARGUMENTS, $1..$n, !cmd and @file; required.

string

Description shown in the TUI.

string

Agent that executes the command; a subagent triggers a subagent invocation by default.

string; defaults to current agent

Forces the command to run as a subagent invocation.

boolean

Overrides the default model for this command.

string

Catch-all permission rule.

allow, ask, deny

Reading a file (matches the file path); .env files denied by default.

allow, ask, deny or object; default allow

All file modifications (edit, write, patch, apply_patch).

allow, ask, deny or object

File globbing (matches the glob pattern).

allow, ask, deny or object

Content search (matches the regex pattern).

allow, ask, deny or object

Listing files.

allow, ask, deny or object

Running shell commands (matches parsed commands).

allow, ask, deny or object

Launching subagents (matches the subagent type).

allow, ask, deny or object

Loading a skill (matches the skill name).

allow, ask, deny or object

Running LSP queries (currently non-granular).

allow, ask, deny or object

Asking the user questions during execution.

allow, ask, deny

Fetching a URL (matches the URL).

allow, ask, deny

Triggered when a tool touches paths outside the project working directory.

allow, ask, deny or object; default ask

Triggered when the same tool call repeats 3 times with identical input.

allow, ask, deny; default ask

Disables the LSP server.

boolean

Command to start the LSP server; required unless only disabling.

string[]

File extensions the LSP server handles.

string[]

Environment variables set when starting the server.

object

Initialization options sent in the LSP initialize request.

object

Disables the formatter.

boolean

Formatting command; $FILE is replaced with the file path. Required for custom formatters.

string[]

Environment variables set when running the formatter.

object

File extensions the formatter handles.

string[]

MCP connection type.

"local" or "remote"; required

Command and arguments to run a local MCP server.

array; required for local

Working directory for a local MCP server process; relative paths resolve from the workspace.

string

Environment variables for a local MCP server.

object

Enables or disables the MCP server on startup.

boolean

Timeout in ms for fetching tools from the MCP server.

number; default 5000

URL of a remote MCP server.

string; required for remote

Headers sent to a remote MCP server.

object

OAuth config for a remote server, or false to disable OAuth auto-detection.

object or false

OAuth client ID; dynamic client registration is attempted if omitted.

string

OAuth client secret, if required.

string

OAuth scopes to request.

string

tui.json: Sets the UI theme.

string; default opencode

tui.json: Customizes keyboard shortcuts; merged with built-in defaults.

object

tui.json: How long OpenCode waits after the leader key, in ms.

number; default 2000

tui.json: macOS-style scroll acceleration; overrides scroll_speed when enabled.

boolean

tui.json: TUI scroll speed; ignored when scroll_acceleration is enabled.

number, minimum 0.001; default 3

tui.json: Diff rendering.

"auto" or "stacked"

tui.json: Terminal cursor style in input fields; default restores the terminal cursor.

block, underline, line, default; default block

tui.json: Cursor blinking; no effect when style is default.

boolean; default true

tui.json: Mouse capture in the TUI.

boolean; default true

tui.json: Enables all attention notifications and sounds.

boolean; default false

tui.json: Allows terminal-mediated desktop notifications.

boolean; default true

tui.json: Allows attention sounds.

boolean; default true

tui.json: Default sound volume.

number 0-1; default 0.4

tui.json: Sound pack ID.

string; default opencode.default

tui.json: Overrides sound files for default, question, permission, error, done, or subagent_done.

object of paths

SKILL.md frontmatter: Skill name; 1-64 lowercase alphanumeric chars with single hyphens, matching the directory name. Required.

^[a-z0-9]+(-[a-z0-9]+)*$

SKILL.md frontmatter: Skill description; required.

1-1024 characters

SKILL.md frontmatter: Optional license field.

string

SKILL.md frontmatter: Optional compatibility field.

string

SKILL.md frontmatter: Optional string-to-string map for tool-specific behavior.

map

SKILL.md frontmatter: Exposes the skill as a /name command in the TUI.

"true"

SKILL.md frontmatter: Set false to keep the skill out of model-facing auto-selection guidance.

"false"

GitHub Action input: model in provider/model format; required.

string

GitHub Action input: primary agent to use; falls back to default_agent or build.

string

GitHub Action input: custom prompt overriding default behavior; required for issues, schedule and workflow_dispatch events.

string

GitHub Action input: comma-separated case-insensitive trigger phrases.

default /opencode,/oc

GitHub Action input: model variant for provider-specific reasoning effort.

e.g. high, max, minimal

GitHub Action input: base URL for the OIDC token exchange API, for custom GitHub App installs.

default https://api.opencode.ai

GitHub Action input: use a caller-provided GITHUB_TOKEN instead of an OIDC-exchanged app token.

boolean; default false

Advanced keybind value: an object with key, event, preventDefault, or fallthrough; strings may hold comma-separated shortcuts and arrays hold alternatives.

string, array, or object