GuidesHosting choices

OpenCode config: opencode.json, precedence and permissions

Where OpenCode 2 reads opencode.json, which file wins, opencode debug config, and permissions: allow, ask and deny rules, last match wins, per agent.

November 14, 2026The Everpod team
The short answer

OpenCode 2 reads opencode.json or opencode.jsonc from your global folder, ~/.config/opencode/, from a project’s root or its .opencode/ folder, and on Linux from /etc/opencode/ for the whole machine. A closer file wins over a farther one, any file inside .opencode/ wins over every file outside one, settings that don’t conflict are kept from all of them, and the machine-wide file beats everything. opencode debug config lists the sources in effect. Permissions are an ordered permissions list of rules, each an action, a resource and an effect of allow, ask or deny, and the last rule that matches wins. This page describes OpenCode 2.3.0; version 1 called the key permission.

{
  "$schema": "https://opencode.ai/config.json",
  "permissions": [
    { "action": "shell", "resource": "*", "effect": "ask" },
    { "action": "shell", "resource": "git status *", "effect": "allow" },
    { "action": "shell", "resource": "git diff *", "effect": "allow" },
    { "action": "shell", "resource": "git push *", "effect": "deny" }
  ]
}
Copied

Where the files go

Either name works, and the config page suggests .jsonc “when you want comments or trailing commas.” Keep one per folder: OpenCode loads both if both are there. The $schema line gives your editor validation and autocomplete. The places, on Linux:

ScopeFile
Every project of yours
~/.config/opencode/opencode.json
One project
opencode.json at its root, or .opencode/opencode.json
Every user on the machine
/etc/opencode/opencode.json

The same folders hold more than the config file: agents/, skills/ and plugins/ sit beside it in ~/.config/opencode/ and in a project’s .opencode/. The skills guide and the MCP servers guide cover the keys those features add.

What wins when several are present

OpenCode searches from the directory you start it in up to the filesystem root. It merges the plain opencode.json files it finds from the farthest directory to the closest, then the ones inside .opencode/ folders in the same order, so, in the docs’ words, “every discovered .opencode config overrides every direct config.” In a monorepo, from lowest precedence to highest:

1. ~/.config/opencode/opencode.json
2. /home/user/projects/acme/opencode.json
3. /home/user/projects/acme/packages/web/opencode.json
4. /etc/opencode/opencode.json
Copied

Started in packages/web, the package’s file overrides the repository’s on any setting both make, and “settings that do not conflict are preserved.” The global file sits below every project file. The system file sits above all of them, so its values are ones users and projects “cannot override.” On a shared server, that is the place for a setting nobody should change.

Seeing what is in effect

opencode debug config    # the configuration sources in effect
opencode debug paths     # OpenCode's global folders on this machine
opencode reload          # apply config changes without restarting the server
Copied

Run opencode debug config from the project directory, since the project files it finds depend on where you start. In version 2 your sessions run in a background service, and the CLI reference says opencode reload “reloads configuration without restarting the server,” with running sessions picking up the change “at the next step boundary.”

Keys from the environment, not in the file

{env:NAME} in a value is replaced by that environment variable, and {file:path/to/file} by the file’s contents, which keeps a key out of a config you commit. An unset variable becomes an empty string, not an error. The config page names no environment variable that points OpenCode at a different config file. The variable has to be set where the background service runs, not only in your shell; installing OpenCode on Linux covers setting one with opencode service set env.

Permissions: the rule shape

A rule has three fields. action is the tool: read, edit, glob, grep, shell, subagent, skill, webfetch, websearch, external_directory and others, with an MCP server’s tools named <server>_<tool>. resource is what the tool is used on: a path for read and edit, the command text for shell, a URL, a skill or an agent. effect is allow (go ahead), deny (block) or ask (“wait for a decision from the client”).

The permissions page states the one rule to remember: “The last matching rule wins, so the specific exceptions follow the broad rule.” That is why the example at the top asks for every command first and carves out git status, git diff and git push after it; with the order reversed, the broad ask would override all three. If no rule matches, OpenCode asks.

What is allowed before you write a rule

Every agent starts from a base policy that allows everything, then asks before reading .env and .env.* files, with .env.example allowed. Your rules come after it, so they override it. Two consequences matter on a server. The shell is not gated by default, and the docs are plain that shell “runs with the host user’s filesystem, process, and network authority.” And files outside the project are open: “The default policy allows external_directory, so external paths are not prompted unless you add a rule.” A tighter starting point keeps secrets and the rest of the machine behind a question:

{
  "$schema": "https://opencode.ai/config.json",
  "permissions": [
    { "action": "shell", "resource": "*", "effect": "ask" },
    { "action": "external_directory", "resource": "*", "effect": "ask" },
    { "action": "read", "resource": "$HOME/reference/*", "effect": "allow" },
    { "action": "read", "resource": "*.env", "effect": "deny" },
    { "action": "read", "resource": "*.env.example", "effect": "allow" }
  ]
}
Copied

Deny narrowly, as here, rather than denying a whole tool. A blanket read deny has a known side effect: with OpenCode’s free models, every request then fails with a misleading free-tier refusal, which “OpenCode’s free tier can only be used from within OpenCode” explains.

When the agent asks

At a prompt you have three answers: once approves only that request; always approves it and saves the tool’s proposed patterns as allow rules for the project, which never override a configured deny; reject refuses it and every other pending request in the session. An unattended opencode run has nobody to answer, and the docs leave it to the client, with “configured deny rules always remain enforced.” opencode run --auto approves every permission that is not explicitly denied, so with it your deny rules are what stands between the agent and the machine.

Per-agent permissions

An agent can carry its own permissions, and they are added to the global list rather than replacing it: “Agent rules are appended after global rules.” Being later, they win where both match. In opencode.json, under agents:

{
  "agents": {
    "reviewer": {
      "description": "Review changes without editing files",
      "mode": "subagent",
      "system": "Focus on correctness, security, and missing tests.",
      "permissions": [{ "action": "edit", "resource": "*", "effect": "deny" }]
    }
  }
}
Copied

Or in the agent’s own Markdown file, .opencode/agents/reviewer.md for one project or ~/.config/opencode/agents/reviewer.md for all, in its frontmatter, which takes the same fields as an agents entry:

---
description: Reviews changes for correctness and regressions
mode: subagent
permissions:
  - action: edit
    resource: "*"
    effect: deny
  - action: shell
    resource: "*"
    effect: deny
---
Copied

A custom subagent uses its own permissions, “not a subset of its parent’s permissions,” and which subagents an agent may start is its subagent rules. The agents page lists the built-in ones; Plan, for instance, explores and plans without editing normal project files.

Above all of these sit policies, which run after the rules and saved approvals and can only take access away: a policy “turns allow or ask into deny and never grants access.” Policies in the global and system files override a project’s, so a project cannot loosen them.

A config written for version 1

Version 2 reads the same files in the same places as version 1, and the migration page says it “normalizes supported V1 and native V2 fields in memory without rewriting the source file,” so an old config keeps working. Tutorials written before version 2 use the old names: version 2 has permissions (an ordered list) for permission, the actions shell for bash, subagent for task and edit for write and patch, and plural agents, providers, commands and plugins. Once a file uses version 2’s shapes, the page warns not to point version 1 at it. If opencode --version starts with 1, the short install line gave you the older release; the OpenCode install guide covers moving to 2.

Run OpenCode on an always-on developer pod.

A developer pod is a permanent cloud computer (VPS), set up and secured for you, with your pick of Claude Code, Codex, OpenCode, Pi, Hermes and OpenClaw installed. Run more agents at once than your laptop can hold, and keep them working when it’s closed. From $24 a month, built in about ten minutes.