Skip to content
Auto Mode Gate

Configure the gate

Auto Mode Gate reads policy from the host that loads the adapter. Restart or reload that host after changing a file.

Configuration paths

Section titled “Configuration paths”
Scope OpenCode Pi
Global $OPENCODE_CONFIG_DIR/auto-mode-gate.json $PI_CODING_AGENT_DIR/auto-mode-gate.json
Global fallback ~/.config/opencode/auto-mode-gate.json ~/.pi/agent/auto-mode-gate.json
Project <project>/.opencode/auto-mode-gate.json <project>/.pi/auto-mode-gate.json

An empty or absent host root uses the fallback. A non-empty root must be an absolute path to an existing regular directory. Relative roots, symlinks, and non-directory roots fail closed. OpenCode never reads the Pi destination, and Pi never reads the OpenCode destination.

See Migrate configuration when upgrading from 0.2.0.

Global configuration

Section titled “Global configuration”
{
  "mode": "enforce",
  "shell": "powershell",
  "trustedExecutablePaths": [
    "C:\\Windows\\System32\\where.exe",
    "C:\\Program Files\\Git\\cmd\\git.exe"
  ],
  "permissionJudge": {
    "enabled": true,
    "model": {
      "provider": "example-provider",
      "id": "example-model"
    },
    "timeoutMs": 15000
  }
}
Key Values Meaning
mode off, shadow, enforce Controls whether denied actions block. Defaults to enforce.
shell bash, powershell, cmd Required before a Bash call can be allowed.
trustedExecutablePaths Absolute path array Exact authority for narrow read-only allowances.
logPath Absolute file path Optional sanitized JSONL decision log.
permissionJudge Strict object Global opt-in, default Pi model, and timeout from 1,000 through 120,000 ms.

Create the log directory before starting the host when logPath is configured.

Project configuration

Section titled “Project configuration”
{
  "mode": "enforce",
  "trustedExecutablePaths": [
    "C:\\Windows\\System32\\where.exe"
  ],
  "permissionJudge": {
    "enabled": false
  }
}

A project can tighten shadow to enforce, remove trusted paths, disable the judge, or reduce its timeout. It cannot enable a globally off gate, relax enforce, set the shell, add trust absent from the global file, set a log path, authorize the judge, change its model, or increase its timeout.

Each configuration file may contain at most 64 KiB, and each trusted-path list may contain at most 256 entries. Unknown keys, invalid JSON, relative file paths, oversized input, and unreadable files fail closed.

Modes

Section titled “Modes”
  • enforce: denied actions block.
  • shadow: policy and logs run, but actions do not block.
  • off: the adapter remains loaded but does not block.

shadow is an observation mode, not a security control.

Next steps

Section titled “Next steps”