OpenCode

Guard OpenCode V2 with a dependency-free plugin that rejects risky tool calls before they run. Version contract, setup, upgrade from V1, files, limits and managed deployment.

DefenseClaw supports OpenCode V2 only (the @opencode/cli package). It installs one plugin that sends each tool call to the gateway before the call runs and rejects it when the verdict is a block. OpenCode talks to its model provider directly; no proxy is involved.

On a per-user install, an explicitly saved guardrail.hook_fail_mode takes precedence over the selected tier. See the gateway outage table and Fail modes.

Platform support

Linux: supportedmacOS: supportedWindows: supported
Min version
2.0.0
Block
Yes
Native ask
No
Fail closed
Yes
Enterprise
machine policy
Support matrix

OpenCode V2 2.2.5 was checked live in per-user and managed installs on Linux, macOS and native Windows. The version contract remains >=2.0.0,<2.3.0.

PlatformStatusNotes
macOS and LinuxSupportedContract >=2.0.0,<2.3.0, source-reviewed at 2.0.0 and 2.1.4; 2.2.5 checked live.
Native Windows x64SupportedThe official @opencode/cli npm package or the current user's SST.opencode WinGet executable, run natively. OpenCode 2.2.5 checked live. WSL, Desktop sidecars, other packages and ARM64 are outside the contract.

Setup

Install OpenCode V2 first. V1 (opencode-ai) and V2 use the same opencode command, so remove V1 when npm installed it:

npm uninstall -g opencode-ai
npm install -g @opencode/cli@2

On a shared computer where you cannot write npm's global prefix, install it for your account instead (npm install -g --prefix ~/.npm-global @opencode/cli@2, with ~/.npm-global/bin first on your PATH).

On a new DefenseClaw install, run defenseclaw init --connector opencode first. Until initialized, setup stops with DefenseClaw is not initialized — run 'defenseclaw init' first. Then:

defenseclaw setup opencode                # first setup defaults to observe: record only
defenseclaw setup opencode --mode action  # reject blocked calls before they run

A re-run without --mode keeps the current mode. On a terminal setup still asks for the mode, with the current one as the default (Enter keeps it), and whether to re-apply the hooks; in action mode it also asks whether to add the LLM judge. --yes skips the questions (the questions setup asks). On Windows, run the same commands in PowerShell.

OpenCode's background server. OpenCode V2 keeps a background server running after its window closes, and that server keeps the plugin it loaded. On Linux and macOS, defenseclaw setup opencode (also with --mode) and defenseclaw uninstall restart your account's own server when it runs, and say so; an open OpenCode window reconnects to it. After an upgrade, on Windows, or when setup says it could not, run opencode service restart yourself. Until OpenCode starts, defenseclaw status shows it as IDLE, which is normal.

One server port per account. The server's default port, 49374, is the same for every account on a computer, so a second account's server cannot start while the first one runs. When your ~/.config/opencode/service.json names no port, setup writes one for your account: 24000 plus your uid (on Windows, the last number of your account SID) modulo 8000, or the next free one when another account holds it. The port is claimed for your account (in /var/tmp, or %ProgramData% on Windows), so it stays the same on later runs and upgrades. Setup keeps a port you set yourself.

On a managed computer the guardian decides the port, and its protected record (opencode-service-ports.json in the guardian's authorization folder, root-only on Linux and macOS and SYSTEM-only on Windows) is the only authority:

  • Each account gets its own port and keeps it, also after it is excluded or deleted, so no other account is ever given it.
  • The guardian writes the recorded port into the account's service.json as that account. A port you set by hand is replaced by the recorded one.
  • A folder on the path to service.json that your account's group can write (Ubuntu and Debian make ~/.config and ~/.config/opencode group-writable) is made sticky by the guardian, as you, and the log says which: another account that holds the group, however it holds it, can then no longer rename or replace your service.json. A folder it cannot make sticky (not yours, or a group that has other members) is refused with the opencode_port_account_unknown warning.
  • The guardian reads an existing service.json once, to keep a port you already chose, and only when it is yours (or root's) and no other account can write it (mode 0600, 0640 or 0644, not 0664). The same folder checks and sticky bit apply before it reads. A file that another account can write is not read for a port: your account gets a fresh port and the guardian writes it into a private copy. A file or folder that belongs to another account is refused with the opencode_port_account_unknown warning.
  • Files are read only in the pass that builds the record: the first pass after install, after an upgrade from a release without the record, or after an administrator removes it. In that pass an account keeps the port its file names if no other account holds it and no other account's file names it. Every account the guardian cannot read in that pass, and every account added later, gets a new port. OpenCode's defaults (49374, 49375) are never kept.
  • A port the files of two or more accounts name in that pass is given to none of them and is marked contested: each of them gets a new port, the guardian logs them all, and no account is given the port until an administrator clears the mark with sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux opencode-port-clear <port> --yes (macOS: sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos opencode-port-clear <port> --yes). On Windows PowerShell, run & "C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw-gateway.exe" enterprise windows opencode-port-clear <port> --yes in an elevated console. An imported port whose account file could not be rewritten is also held from later accounts. Repair that file and clear its held mark with the same command. The command clears only the named port and logs the clear in the protected record.
  • When every port from 24000 to 31999 is held, a new account gets none and the guardian says so.

The guardian reports account and record problems as they occur. status, verify and doctor also show these warnings:

  • opencode_port_account_unknown: the guardian could not read or write an account's service.json (a linked or read-only ~/.config/opencode, a broken file, a home that does not answer). The record does not change and other accounts are not affected. The warning names the account, the file, the reason and the step that clears it, for example opencode service set port <port> as that account, or making ~/.config/opencode a folder the account can write.
  • opencode_port_account_unknown for OpenCode port record for UID <n> (no account found): the guardian kept the unknown entry of an account that has since been deleted, so there is nothing to repair. Status and verify always show it (a warning; the exit code is unchanged). After you check that the UID really has no account, remove the entry with sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux opencode-port-unknown-clear <uid> --yes (macOS: sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos opencode-port-unknown-clear <uid> --yes). The command checks the UID again against the host account lookup, nss-altfiles, systemd-userdb and the local account database, and refuses while any of them still holds it or when the lookup does not answer. The port binding stays reserved. A different account that took the old name keeps a different UID, so the warning for the old UID stays until you run the command.
  • opencode_port_contested: a port is marked contested by several files, or held because an imported account file could not be rewritten; the line names the port, affected accounts and the clear command above.
  • opencode_port_record_unreadable: the record cannot be read, so no account gets a new port; ports already in service.json files stay. Removing the record (sudo rm) makes the guardian build a new one from the accounts' files on the next pass, under the rules above. To keep every binding, repair the record instead of removing it.
  • opencode_port_record_unchecked: a non-root status or doctor cannot open the guardian's folder; on Windows, check in an elevated console. On Linux, check as root with sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux status (macOS: sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos status).

To change an account's port, an administrator edits its entry in the record; the guardian then rewrites that account's service.json on its next pass.

Folder modes. Setup refuses to install the plugin in a folder another account can write. On Ubuntu and Debian (umask 002), ~/.config and ~/.config/opencode are group-writable, but the group is your own private group (named after you, with no other member), so setup accepts them. A folder whose group has other members, or that everyone can write, is refused with the chmod go-w command to run.

Check it

defenseclaw status
defenseclaw doctor

The connector appears under Agents with its mode. Doctor shows the plugin's load heartbeat once OpenCode has started.

Version contract

Installed versionWhat setup does
OpenCode V1, or another major than 2Refuses in every mode, also with DEFENSECLAW_ALLOW_HOOK_CONTRACT_DRIFT=1. Install V2 and run setup again.
A git or source build without a release versionRefuses: its digits do not tell the major version. Install a versioned V2 release.
>=2.0.0,<2.3.0Uses opencode-hooks-v2, plugin generation v7.
A newer V2 minorUses the same contract with an "untested newer version" warning.
Version not readableObserve warns; action refuses without an explicit exploratory override.

Upgrade from DefenseClaw 1.0.5 or earlier

Earlier releases guard OpenCode V1 only, and OpenCode V2 cannot load their plugin.

  • OpenCode V1 still installed: defenseclaw upgrade (and the one-line installer) stops before it changes anything and says to install V2. Your current DefenseClaw keeps guarding OpenCode V1. Install V2, then upgrade again. To upgrade without OpenCode, run defenseclaw setup remove opencode first.
  • OpenCode V2 installed: the upgrade selects V2 and writes the V2 plugin; no setup run is needed. Restart OpenCode's background server afterwards.
  • Rollback: defenseclaw rollback to 1.0.5 or earlier refuses while OpenCode V2 is installed and set up, because that release cannot guard it and its gateway does not start. The rollback restores that release's own configuration, so put OpenCode V1 back first to roll back, then run defenseclaw agent discover --refresh so DefenseClaw sees it, or stay on this release.
  • Downgrade: defenseclaw upgrade --version 1.0.5 (or earlier, and the installers with an older --version) is refused the same way, before anything changes. A downgrade keeps this install's configuration, so defenseclaw setup remove opencode first is the other way through; OpenCode then runs without DefenseClaw.
  • Upgrade DefenseClaw first, then move OpenCode to V2. DefenseClaw 1.0.5 and earlier still list OpenCode as protected when V2 is installed (doctor passes, status shows IDLE), but V2 does not load their plugin, so its tool calls run unchecked and nothing says so.

What it can block or ask

What a gateway outage does to an OpenCode call, per install and fail mode, is in the gateway outage table.

  • In action mode the awaited execute.before callback rejects a blocked call before it runs. OpenCode shows the reason under the tool call, and the model gets it.
  • execute.after only records the result. The tool has already run.
  • OpenCode has no hook that stops a prompt. A matching prompt reaches the model; tool-call rules still block.
  • There is no native ask. A confirm verdict runs the call and adds a DefenseClaw notice with the severity and reason to the tool's result.
  • V2 has no toast. DefenseClaw notices (a confirm verdict, a gateway outage, a reported foreign plugin) appear under the tool call in the result and in OpenCode's log.

Fail mode

Can fail closed: yes, for the awaited execute.before only. Settings and edge cases are in Fail modes.

On a per-user install with no saved mode, a gateway that is not running follows the policy tier: the default and permissive policies let the call run with one warning per session and a hook-failures.jsonl record, and the strict policy blocks it (gateway outage table). The warning appears under the first unchecked tool call of the session. A listener the plugin cannot verify, an error or unusable answer and an install in progress block the call in every tier. Under Secure Client an administrator can choose outage-only open. On a managed standalone host the route decides what an outage does, the machine-policy plugin (the default route) or the per-user plugin (used when machine policy is off or does not apply): both rows and the foreign-hook guard rule are in the gateway outage table. An unverified listener never receives the bearer or payload.

A call whose arguments are larger than the gateway's 1 MiB limit is reviewed in a bounded form: observe mode lets it run and records it, action mode blocks it.

The plugin

The plugin default-exports { id: "cisco.defenseclaw", setup(ctx) } and registers awaited execute.before and execute.after callbacks. It imports only Node built-ins; it needs no OpenCode SDK package and never triggers a package install. Before it waits for a verdict, it takes a detached, frozen copy of the tool's input, so a later plugin cannot swap the arguments that were checked. Session location and MCP server identity come from bounded local V2 API calls; action mode rejects an ambiguous MCP identity.

Native V2 tools are checked with their own fields: shell (command, optional workdir, timeout, background), read and write (path), edit (path, oldString, newString) and patch (patchText). Session events are observe-only telemetry.

The per-user plugin runs the account's own defenseclaw-gateway helper, which checks the connected listener before it sends the scoped token or any event. Doctor detects digest drift, and defenseclaw setup opencode --yes --restart restores the packaged plugin.

Files DefenseClaw changes

WhatWhere
Plugin$OPENCODE_CONFIG_DIR/plugins/defenseclaw.js (default ~/.config/opencode/plugins/defenseclaw.js; Windows %USERPROFILE%\.config\opencode\plugins\defenseclaw.js). OpenCode V2 loads it on its own; opencode.json is not edited.

Setup also writes a connector-scoped token sidecar under ~/.defenseclaw/hooks. Teardown removes the plugin when it is unchanged since setup; a modified plugin is kept and doctor reports the drift. guardrail disable and setup remove opencode refuse before saving while teardown is unverified: preserve your edits, run defenseclaw setup opencode --yes --restart, then retry.

On native Windows the npm image is %APPDATA%\npm\node_modules\@opencode\cli\bin\opencode.exe, and the admitted WinGet path is %LOCALAPPDATA%\Microsoft\WinGet\Packages\SST.opencode_Microsoft.Winget.Source_8wekyb3d8bbwe\opencode.exe. Setup verifies the executable and its package before it writes anything.

Enterprise deployments

On a managed computer

The per-user defenseclaw setup and defenseclaw guardrail commands on this page refuse on a standalone enterprise host, on Windows too, and defenseclaw status shows the user's own protection state there (see Managed command availability). An administrator adds guardrail.connectors.opencode: {} to the managed config.yaml, applies it through the enterprise lifecycle, and runs enterprise policy verify. DefenseClaw registers its plugin folder in OpenCode's managed config (/etc/opencode/opencode.json on Linux, /Library/Application Support/opencode/opencode.json on macOS; on Windows C:\ProgramData\opencode\opencode.json, whose plugin entry points at the folder of C:\Program Files\Cisco\DefenseClaw\share\opencode\index.js). The per-user plugin file above is not used there. Set guardrail.connectors.opencode.enabled: false in the managed config to turn it off. Machine policy describes the route.

The plugin lives at <install root>/share/opencode/index.js. Under application control OpenCode must be allowed to read it; OpenCode skips a plugin it cannot read and runs without DefenseClaw. On Linux the deb and rpm ship the plugin, so fapolicyd's package-database trust covers it. For a tarball, add the installed tree to fapolicyd trust on a fresh install or update its existing entry after staging an upgrade or rerun (application control).

Managed hosts need OpenCode V2 too. OpenCode V1 loads the V2 plugin but never runs it, so while a user can still run V1, status, verify and ensure warn opencode_v1_unprotected for that user with the remedy, and coverage_complete is false. Nothing is blocked or removed. When several users share one machine-wide copy (a prefix such as /opt/agents), the output has one line naming the copy and the number of users, not one line per user, and it names none of them (the root-only unprotected-agents.json beside the target manifest names them); a copy inside one user's home keeps its own line. An approved directory plugin is now approved by its content: after this upgrade, approve the new digest of each previously approved plugin folder.

In an OpenShell sandbox

The image pins OpenCode 2.1.4 from the official @opencode/cli package, with package integrity and the native binary digest checked. Sessions use --standalone; the launcher refuses --server. The V1 sandbox certification does not cover V2: the V2 image is unverified and not selectable until a fresh OpenShell ingress, block and egress check passes.

Limits

  • Only V2 is supported. No setting or override enables a detected V1.
  • The plugin checks tool calls and their results; it does not intercept model traffic.
  • There is no native approval: a confirm verdict runs with a notice.
  • OpenCode 2.2.5 has no pure mode: there is no --pure flag, and it does not read OPENCODE_PURE (OpenCode V1 skipped plugins with them).
  • The background server's port: per-user setup (Linux, macOS and Windows) gives your account its own port when ~/.config/opencode/service.json names none, and keeps one you set. On a managed computer the guardian's record decides and replaces a port you set (see above). A running server moves at its next start (opencode service restart).
  • OpenCode keeps runtime files in /tmp/opencode, which belongs to the first account that ran it; another account's OpenCode then fails with EACCES. Point TMPDIR at a folder of your own before you start OpenCode (for example export TMPDIR=$HOME/.cache/tmp, after mkdir -p of it). Both are OpenCode's own behavior.

Disable

For a per-user, single-connector install:

defenseclaw guardrail disable --yes

Disabling removes DefenseClaw's plugin and preserves your other OpenCode settings. defenseclaw guardrail enable reinstalls DefenseClaw's plugin. To remove the connector, run defenseclaw setup remove opencode --yes (add --force if it is the last one). If you modified the plugin, guardrail disable and setup remove refuse before saving; run defenseclaw setup opencode --yes --restart to restore it, then retry. On a multi-connector install, add --connector opencode to guardrail disable and guardrail enable. Restart OpenCode's background server afterwards (opencode service restart).