Getting started

Protect your AI agent in seconds. Pattern detection is active the moment the sidecar starts; enhanced ML detection downloads silently in the background. Zero-knowledge by architecture — raw prompts, responses, action parameters, and PII never leave your machine.

1 Install

curl -fsSL https://getcrawdad.dev/install.sh | sh

The script detects your platform, downloads the signed binary from the R2 CDN, installs it to /usr/local/bin/crawdad-sidecar, and registers the sidecar to run automatically:

Install is fast because only the binary is fetched. Pattern detection activates immediately. On first run the sidecar downloads the ML model and platform-specific libonnxruntime in the background — you'll see a one-line progress indicator in the dashboard. When it finishes, the dashboard shows "Full detection ready — restart to activate." The next restart (reboot, update, or manual) loads ML and full detection is live. The download runs exactly once per machine; subsequent starts use the on-disk model.

• macOS: LaunchAgent at ~/Library/LaunchAgents/com.crawdad.sidecar.plist
• Linux: systemd unit at /etc/systemd/system/crawdad-sidecar.service (prompts for sudo)

2 Point your agent at the proxy

One environment variable per provider. No code changes required.

# Anthropic (Claude Code, Anthropic SDK):
export ANTHROPIC_BASE_URL=http://localhost:7748

# OpenAI (GPT SDK, Cursor):
export OPENAI_BASE_URL=http://localhost:7747

# Google (Gemini, Google ADK):
export GOOGLE_API_ENDPOINT=http://localhost:7746

# xAI / Grok:
export XAI_BASE_URL=http://localhost:7745

# NVIDIA NIM: port 7744

Your agent still talks to the same SDK, same request and response format. Every request passes through the 7-layer detection pipeline before reaching the upstream model. Allowed requests are forwarded unchanged.

Claude Code: export ANTHROPIC_BASE_URL=http://localhost:7748 in your shell (or add to ~/.zshrc / ~/.bashrc) and restart the terminal. Verified end-to-end on real-world request sizes; the large-request-body truncation that affected Claude Code sessions was fixed in v0.9.2.

3 Open the dashboard

open http://localhost:7750

You'll see overview cards (request counts, detection stats, red team trend), a Run Test Battery button that fires 24 curated adversarial payloads through the live pipeline, per-session timeline, agent and MCP inventory, and the audit trail. The first-run Connect Agent wizard walks through setting the env var for your agent and confirms the connection the moment proxied traffic arrives.

4 Verify

Quickest check: the dashboard loads and clicking Run Test Battery returns a results table with blocks, allows, and per-layer decisions.

Command-line alternatives:

crawdad-sidecar --version            # prints 0.10.1
curl http://127.0.0.1:7749/v1/health  # internal control port
# {"status":"ok","mode":"zero-knowledge","device_id":"d_..."}

5 Set trust levels per agent

Open the Agents page in the dashboard. Every agent Crawdad has seen is listed with a colored trust level dot and a level selector:

Each request is attributed to a specific agent at connection time by resolving the caller's TCP socket to its owning PID, walking up the parent process tree until a known agent signature matches. Enforcement is per-agent — quarantining one agent never blocks another on the same provider.

Detections automatically lower trust: an injection attempt on a Monitored agent escalates to Restricted; a second attempt or a critical-severity hit escalates to Quarantined. Quiet periods auto-recover one level at a time. Every transition is recorded in the audit trail with its trigger and whether it was manual or automatic. Escalation is configurable per-agent, including an off switch.

Pause and protection modes

Crawdad has four protection modes selectable from the dashboard header pill: Maximum, Standard, Reduced, and Paused. Standard is the default. Reduced flags most categories instead of blocking. Paused suppresses blocking entirely while continuing to detect and record forensically — useful when Crawdad is blocking something legitimate and you need to ship. Pause durations are 5 minutes, 15 minutes, 1 hour, or until you manually unpause. The sidecar enforces auto-unpause server-side.

6 Connect your phone

Open Settings → Connect Device in the dashboard. A QR code appears; scan it from any phone browser. The pairing handshake exchanges device keys over your LAN — your phone and the sidecar need to be on the same WiFi for this one-time step. After pairing, the mobile app works from anywhere via the encrypted relay. If your desktop's LAN IP changes later (e.g. after a reboot), the phone races a 3-second direct probe and falls back to the encrypted relay automatically.

What you get on the phone:

• Home: one-line health bar (uptime, requests inspected today, blocked today), big 0–100 security score with tappable sub-score breakdown (trust posture / detection health / alert hygiene) and trend arrow, three-up activity stats (Today / Week / Month), and per-agent trust-level dots.
• Alerts: severity / agent / category filter chips, per-alert Acknowledge / Quarantine / Investigate buttons. Investigate shows only detection metadata (time, agent, category, pattern, severity, verdict) — never content. Mark-all-read clears unread.
• Agent detail: tap an agent to see a 24-hour activity sparkline, tool usage chips, behavioral-status line, and the full four-level trust selector.
• Quick actions (FAB): Run Test Battery fires the 24-payload adversarial spectrum and surfaces results in your alert feed. Pause All Agents is one-tap fleet quarantine for emergencies, with a confirm dialog.
• Settings: notification preferences (severity threshold, per-agent mute toggles, quiet hours — all stored on the phone; the sidecar never sees them). Privacy toggle Anonymize tool names maps real tool names to six generic buckets (file_read, file_write, shell, web, api_call, other) in the remote state snapshot.

Every remote command is Ed25519-signed by the paired device and replay-protected on the sidecar. The relay sees encrypted blobs only — prompts, responses, tool calls, and PII never leave your machine. Per-device rate limits (5 trust changes / 10 min, 1 quarantine release / hour), an optional PIN gate for sensitive actions, and a desktop-side kill switch round out the safety rails.

Supported platforms

The production scan path runs at 99.8% detection and 0% false-positive rate on the open 497-attack / 1,172-negative benchmark at contemporary-agent-attacks (CC-BY 4.0, reproducible by any third party). The stack is: pattern layers (L1 + semantic heuristics + indirect injection + session context + PII) plus a fine-tuned DeBERTa-small ML classifier (FP16, ~272 MB, auto-downloaded). Operators can set CRAWDAD_ML_BLOCK=0 for pattern-only mode with no ML blocking.

Data directory

Crawdad creates its data directory with 0700 permissions on first run. The sidecar refuses to start on a group- or world-accessible path — this is defense-in-depth for the zero-knowledge claim.

curl -fsSL https://getcrawdad.dev/deploy/setup.sh | bash

pip install crawdad-sdk

from crawdad import CrawdadClient
client = CrawdadClient(base_url="http://localhost:7748")
result = client.firewall_scan("Test message")
# result.verdict = "Safe" | "Blocked"