Connectors
Every DefenseClaw connector shares one adapter interface, and each one exposes only the hook, plugin, policy, ACP, telemetry and approval capabilities its agent offers.
A connector is how DefenseClaw guards one coding agent. Hook connectors register with the agent's own hooks or plugin, and the agent keeps talking to its model provider directly. Proxy connectors send the agent's model traffic through the DefenseClaw guardrail proxy.
Connectors are the adapter layer between agent frameworks and DefenseClaw. They share one Go interface, but each connector advertises only the capabilities its agent actually exposes. Proxy routing, lifecycle hooks, subprocess wrapping, telemetry and approval support therefore vary by connector.
Pick yours
| Agent | Type | Can block | Can ask you first | OS |
|---|---|---|---|---|
| Claude Code | Hook | Prompts and tool calls | PreToolUse | Linux, macOS, Windows |
| Codex | Hook | Prompts and tool calls | No | Linux, macOS, Windows |
| GitHub Copilot CLI | Hook | Tool calls | No: a confirmation blocks | Linux, macOS, Windows |
| Cursor | Hook | Prompts and tool calls | No | Linux, macOS, Windows |
| Devin | Hook | Prompts and tool calls | No | Linux, macOS, Windows |
| Antigravity | Hook | PreToolUse | PreToolUse | Linux, macOS, Windows |
| Kiro | Hook | Tool calls; prompts in Kiro IDE | No | Linux, macOS, Windows |
| OpenCode | Plugin | Tool calls | No | Linux, macOS, Windows |
| Amp | Plugin | Tool calls and results | tool.call, tool.result | Linux, macOS, Windows |
| Hermes | Hook | pre_tool_call | No | Linux, macOS, Windows |
| OpenClaw | Proxy | Requests, responses, tool calls | before_tool_call | Linux, macOS |
| ZeptoClaw | Proxy | Requests, responses, tool calls | No | Linux, macOS |
Where an agent cannot ask, a confirm verdict becomes an alert with the original action kept; Copilot CLI blocks it instead. You can review it in audit or the TUI, but you cannot resume the call. The capability matrix has the full per-connector detail, and Human approval has the per-event matrix.
Claude Cowork, the agent mode of Claude Desktop, runs through the Claude Code connector's hooks. It is not a connector of its own. See Claude Cowork.
One gateway can serve several hook connectors, each with its own posture under guardrail.connectors.<name>. Choose Add, not Replace, when you run a second setup <connector>. Proxy connectors own the traffic plane and cannot be combined this way. See Multi-connector.
Platform support
What each OS supports, and what live tests verified. Switch to Enterprise for the managed edition. The support matrix adds features by edition.
| Agent | Linuxx86_64, arm64 | macOSApple silicon | Windowsx64 | Min versionlowest tested |
|---|---|---|---|---|
| Claude CodeNative hooks | Supported | Supported | Supported | 2.1.154 |
| CodexNative hooks | Supported | Supported | Supported | 0.124.0 |
| GitHub Copilot CLINative hooks | Supported | Supported | Supported | 1.0.18 |
| CursorNative hooks | Supported | Supported | Supported | 2.4.0 |
| DevinNative hooks | Supported | Supported | Supported | 3000.4.25 |
| AntigravityNative hooks | Supported | Supported | Supported | 1.1.8 |
| KiroNative hooks | Supported | Supported | Supported | kiro-cli 2.27.1; Kiro IDE 1.0.182 |
| OpenCodePlugin | Supported | Supported | Supported | 2.0.0 |
| AmpPolicy plugin | Supported | Supported | Supported | 0.0.1785334225 |
| HermesNative hooks | Supported | Supported | Supported | 0.19.0 |
- Linux
- Supported
- macOS
- Supported
- Windows
- Supported
- Linux
- Supported
- macOS
- Supported
- Windows
- Supported
- Linux
- Supported
- macOS
- Supported
- Windows
- Supported
- Linux
- Supported
- macOS
- Supported
- Windows
- Supported
- Linux
- Supported
- macOS
- Supported
- Windows
- Supported
- Linux
- Supported
- macOS
- Supported
- Windows
- Supported
- Linux
- Supported
- macOS
- Supported
- Windows
- Supported
- Linux
- Supported
- macOS
- Supported
- Windows
- Supported
- Linux
- Supported
- macOS
- Supported
- Windows
- Supported
- Linux
- Supported
- macOS
- Supported
- Windows
- Supported
Version and platform notes
- Claude Code
- Windows: Native executable hooks. WSL is outside the native contract.
- Codex
- Windows: System PowerShell bridge to the packaged hook executable.
- GitHub Copilot CLI
- Windows: Uses Copilot CLI's PowerShell hook field.
- Cursor
- Cursor Desktop 2.4.0 up to 4.0.0. The Cursor Agent CLI is covered only at the reviewed build 2026.07.23-e383d2b. Windows: Managed PowerShell adapter.
- Devin
- Reviewed Devin CLI 3000.4.25 on every OS and 3000.11.3 on Linux; newer builds run as untested newer versions. Windows: Devin's own hook runner starts the protected hook executable directly; no PowerShell bridge.
- Antigravity
- Windows: Packaged PowerShell hook launcher.
- Kiro
- Below 2.27.1, kiro-cli has non-interactive --v3 runs that load no hooks, and an IDE before 1.0.182 cannot read global hooks. Per-user and managed setup refuse an older kiro-cli or an older IDE, in every guardrail mode, when no supported Kiro form is installed beside it. A Kiro form whose version could not be read is unknown and not protected: action setup refuses it unless a supported form is installed, and doctor and managed status report it. Managed status reports a below-floor product as uncovered and verify fails. Earlier managed CLI enrollments keep their interactive hooks across upgrade until updated. A supported Kiro IDE can be enrolled beside an older CLI.
- OpenCode
- V2-only contract covers 2.0.0 up to 2.3.0. Version 2.2.5 was checked live on Linux, macOS and native Windows in per-user and managed installs; 2.2.3 and 2.2.4 were checked on selected platforms. Newer V2 minors are untested; V1 and unversioned git builds are refused.
- Amp
- Windows: Owner-only TypeScript plugin in the user plugin directory.
- Hermes
- Contract covers 0.19.0 up to 0.22.0. Before 0.21.1 the TUI (hermes --tui) and dashboard chat run tools without the hooks; setup and doctor warn. Windows: Hermes' own terminal tool needs its bundled Git Bash.
| Agent | Linux.rpm | macOS.pkg | WindowsSetup.exe |
|---|---|---|---|
| Claude CodeNative hooks | SupportedMachine policy | SupportedMachine policy | SupportedMachine policy |
| CodexNative hooks | SupportedMachine policy | SupportedMachine policy | SupportedMachine policy |
| GitHub Copilot CLINative hooks | SupportedMachine policy | SupportedMachine policy | SupportedMachine policy |
| CursorNative hooks | SupportedMachine policy | PreviewMachine policy | SupportedMachine policy |
| DevinNative hooks | SupportedPer-user | SupportedPer-user | SupportedPer-user |
| AntigravityNative hooks | SupportedPer-user | SupportedPer-user | SupportedPer-user |
| KiroNative hooks | PreviewPer-user | PreviewPer-user | SupportedPer-user |
| OpenCodePlugin | SupportedMachine policy | SupportedMachine policy | SupportedMachine policy |
| AmpPolicy plugin | SupportedPer-user | SupportedPer-user | SupportedPer-user |
| HermesNative hooks | SupportedPer-user | SupportedPer-user | SupportedPer-user |
- Linux
- SupportedMachine policy
- macOS
- SupportedMachine policy
- Windows
- SupportedMachine policy
- Linux
- SupportedMachine policy
- macOS
- SupportedMachine policy
- Windows
- SupportedMachine policy
- Linux
- SupportedMachine policy
- macOS
- SupportedMachine policy
- Windows
- SupportedMachine policy
- Linux
- SupportedMachine policy
- macOS
- PreviewMachine policy
- Windows
- SupportedMachine policy
- Linux
- SupportedPer-user
- macOS
- SupportedPer-user
- Windows
- SupportedPer-user
- Linux
- SupportedPer-user
- macOS
- SupportedPer-user
- Windows
- SupportedPer-user
- Linux
- PreviewPer-user
- macOS
- PreviewPer-user
- Windows
- SupportedPer-user
- Linux
- SupportedMachine policy
- macOS
- SupportedMachine policy
- Windows
- SupportedMachine policy
- Linux
- SupportedPer-user
- macOS
- SupportedPer-user
- Windows
- SupportedPer-user
- Linux
- SupportedPer-user
- macOS
- SupportedPer-user
- Windows
- SupportedPer-user
Route notes
- Kiro
- Editors that start Kiro over ACP are enrolled with `defenseclaw-gateway enterprise acp enroll` (preview).
- OpenCode
- Machine policy through the managed OpenCode plugin that the standalone package installs; per-user when that plugin is missing.
OpenClaw and ZeptoClaw need the guardrail proxy, which native Windows does not host.
OpenShell sandbox
defenseclaw sandbox run <harness> runs a coding agent in an NVIDIA OpenShell sandbox. The sandbox guide has setup and every command.
- Run today: Claude Code, Codex, GitHub Copilot CLI, Kiro, Hermes and Antigravity.
- Cannot run yet: OpenCode, Amp, Cursor and Devin have not passed the required live sandbox hook check. OpenCode needs a fresh V2 run; the other three need a vendor account before an agent turn.
OpenClaw and ZeptoClaw do not run in a sandbox.
How a connector is structured
Every connector implements one Go interface, defined in internal/gateway/connector/connector.go. Each connector reports only the capabilities its agent offers, so proxy routing, hooks, subprocess wrapping, telemetry and approval support differ per agent. Use the capability matrix to compare them and the hook contracts page for supported agent versions.
| Method | Runs | Purpose |
|---|---|---|
Name, Description | Always | Identify the connector. |
ToolInspectionMode, SubprocessPolicy | Always | Report how tool calls are inspected and whether setup installs PATH shims. |
Setup | When an agent is wired in | Back up the agent config and add DefenseClaw's hooks, plugin or provider entries. |
Teardown | When an agent is taken out | Restore the config, or remove only DefenseClaw's entries. |
VerifyClean | After Teardown, and before another connector's Setup | Fail with a list of leftover hooks, env files, config patches or shims. |
Authenticate | On each request | Accept or refuse the caller. |
Route | On each proxied LLM request | Read the request signals the proxy needs. |
SetCredentials | At gateway boot | Give the connector the gateway token and master key. |
Two optional interfaces cover the rest. HookEndpoint lets a connector declare its hook route, for example /api/v1/codex/hook, which the gateway's API server registers when it starts. NotifyEndpoint does the same for an auxiliary notify bridge. Cursor and the other hook-only connectors share hook_only.go. Other connectors have a file of their own, such as claudecode.go, codex.go and devin.go.
List view for small screens. Use the expand button to open the drawing.
- 1.Wire the agent inSetup backs up the configand adds the hooks
- on removalTake it out
- 2.Take it outTeardown restores the config
- thenCheck it is clean
- 3.Check it is cleanVerifyClean finds no leftovers
List view for small screens. Use the expand button to open the drawing.
- AgentLLM request
- proxiedCheck the caller
- Check the callerAuthenticate
- acceptedRead the request
- Read the requestRoute
Hook and proxy paths
| Hook connector | Proxy connector | |
|---|---|---|
| Data path | The agent talks to its upstream directly. | The agent's model calls go through the guardrail proxy (port 4000 by default). |
| Enforcement | Only the events the selected hook contract declares as blocking. | Request and response policy in the proxy, plus tool-call checks. |
| Several at once | Yes, each with its own posture under guardrail.connectors.<name>. | No. A proxy connector owns the traffic plane. |
| OS | Linux, macOS, Windows | Linux, macOS |
Next
- Hook contracts: supported agent versions per connector.
- Upgrade: connectors that were renamed or removed.
Paths and troubleshooting
Native Windows filesystem locations, supported overrides, safe diagnostics, and post-install and post-upgrade verification.
Capability matrix
Per-connector breakdown of block capability, native ask events, fail-closed support, subprocess policy, OpenShell sandbox tier, and HITL behaviour. The single source of truth for "can this connector do X?"