Connectors

ZeptoClaw

ZeptoClaw routes through DefenseClaw via api_base redirect plus response-scan. Full guardrail pipeline runs on every request.

ZeptoClaw is the second proxy connector. DefenseClaw rewrites ~/.zeptoclaw/config.json providers to point at the local guardrail proxy; every request is inspected on its way out and every response on its way back.

Setup

defenseclaw setup zeptoclaw --mode observe --restart
defenseclaw setup zeptoclaw --mode action --rule-pack default --restart

ZeptoClaw connector setup is supported on macOS and Linux. ZeptoClaw publishes macOS/Linux builds and its DefenseClaw integration requires the guardrail proxy, so native Windows setup is unsupported.

setup zeptoclaw is the dedicated ZeptoClaw alias. It delegates to the shared guardrail setup backend and exposes the proxy connector's common setup options; it is not a byte-for-byte copy of every setup guardrail flag. See the quick-alias reference for the alias and full guardrail setup for the complete wizard. The proxy is always in the data path: --mode observe records without policy blocking, while --mode action enforces.

What this command sets vs. leaves at defaults

The flags above explicitly set: connector, mode, and (optionally) rule pack. Every other knob falls back to the values DefenseClaw ships with — schema-defined in internal/config/config.go and documented on the Defaults page.

KnobValue when omittedFlag to override
Scanner backendlocal (bundled regex packs, zero key)--scanner-mode local|remote|both
Rule packunset → built-in baseline (no overlay)--rule-pack default|strict|permissive
LLM judgeoff (regex-only triage)--judge-model <model> plus --judge-api-key-env
Detection strategyregex_judge if judge is on, else regex-only--detection-strategy regex_only|regex_judge|judge_first
HITLoff (no operator approval prompts)--human-approval plus --hilt-min-severity ...
HITL minimum severityHIGH (when --human-approval is on; stored uppercase in config)--hilt-min-severity low|medium|high|critical (case-insensitive)
Hook fail-modecurrent config; closed on a fresh install (open is retained for migrated legacy configs)defenseclaw guardrail fail-mode <open|closed> (no flag)
Proxy port4000--port <int>
Block messageempty (uses built-in copy)--block-message "<text>"
Redactionv8 bucket/profile policy (none for fresh v8)Edit observability.destinations[].routes[].selector.buckets and observability.redaction_profiles; then follow Redaction → Verify policy.
Verify after setupon--no-verify

See the full flag reference for the complete table or run defenseclaw setup guardrail --help.

Common variations — pick the recipe that fits your phase

defenseclaw setup zeptoclaw \
  --mode observe \
  --rule-pack permissive \
  --restart

The proxy is in the data path but nothing blocks. Every collected prompt and response produces a projection in mandatory SQLite event history. On a fresh v8 configuration, the effective local profile is none, so registered prompt, response, tool, path, and identifier fields can remain full fidelity. A global or bucket profile can redact the local projection; optional destinations receive their own selected projection. Run this for at least a week before promoting — see Defaults → tuning by risk tolerance.

defenseclaw setup zeptoclaw \
  --mode action \
  --human-approval \
  --hilt-min-severity high \
  --restart

HIGH findings can produce a raw confirm action; CRITICAL still blocks unconditionally. ZeptoClaw has no native ask surface, so confirm takes its immediate fallback with raw_action preserved. The TUI and audit log can review the event but cannot approve and resume it. See the HITL page for the per-connector matrix.

export DEFENSECLAW_LLM_KEY='replace-with-your-key'

defenseclaw setup zeptoclaw \
  --mode action \
  --human-approval \
  --hilt-min-severity high \
  --detection-strategy regex_judge \
  --judge-model anthropic/claude-sonnet-4-20250514 \
  --judge-api-key-env DEFENSECLAW_LLM_KEY \
  --restart

Adds the configured LLM judge as a second pass on regex-flagged prompts. Latency and provider cost depend on the selected judge model.

defenseclaw policy activate strict
defenseclaw setup zeptoclaw \
  --mode action \
  --rule-pack strict \
  --restart

Block MEDIUM and above, alert on LOW, and do not offer approval for findings that have already crossed the block threshold. Pair it with the OpenShell sandbox profile and a reviewed first-party allow-list for additional containment.

Treat local event history as sensitive data

The mandatory database is configured by observability.local (by default, ~/.defenseclaw/audit.db) and retains 90 days on a fresh configuration. Set observability.local.retention_days to the reviewed retention period and limit host access to the DefenseClaw data directory. A global observability.defaults.redaction_profile or a bucket redaction_profile also governs SQLite; a destination or route profile governs only that export trust boundary. Verify the effective result with defenseclaw config show --effective --section observability and defenseclaw observability plan. See Redaction for the resolution order and Observability for retention behavior.

Decision aids — should I turn this on?

Human-in-the-loop (HITL)

ZeptoClaw has no native ask. Confirm uses an immediate fallback with raw_action preserved for review.

Mode + judge recipes

Side-by-side bash for observe / action / action+HITL / action+judge — copy-paste ready.

Defaults & rule packs

What permissive / default / strict actually ship, and which one matches your risk tolerance.

Interactive wizard

Animated terminal demo of the prompt-by-prompt setup flow — the safest path the first time.

Not sure what to pick? Run defenseclaw setup guardrail (no flags) — the interactive wizard walks you through every choice with safe defaults pre-selected and inline help. The Prompt → flag mapping table gives you the CI-shaped command for the same configuration.

Files DefenseClaw will modify

config.json (providers.*.api_base, safety.allow_private_endpoints)

safety.allow_private_endpoints is set to true so the rewritten api_base (a 127.0.0.1 URL) is accepted.

Hook capabilities

The proxy can block inspected requests, responses, and tool-call payloads. ZeptoClaw has no native ask event.

ZeptoClaw has no native ask surface. Confirm verdicts take an immediate fallback with raw_action preserved so operators can review the original request in the TUI or audit log; neither surface can resume it.

Subprocess policy

sandbox — see Sandbox setup for the openshell-sandbox workflow.

Disable

defenseclaw guardrail disable --yes

Windsurf

Windsurf connector wires Cascade hooks across pre_user_prompt, pre_read_code, pre_write_code, pre_run_command, and pre_mcp_tool_use.

Capability Matrix

Per-connector breakdown of block capability, native ask events, fail-closed support, subprocess policy, and HITL behaviour. The single source of truth for "can this connector do X?"