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. Raw prompts, responses, action parameters, and PII stay on your machine by default.

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

The easiest path is the dashboard's Connect Agent screen: it discovers the agents already running on your machine and gives each routable tool a one-click Connect that writes the correct configuration for you and makes it persistent (a fenced # >>> crawdad >>> block in your shell rc, or a merged provider entry in ~/.codex/config.toml). It never edits a file silently — you see exactly what it will write, then confirm once. To do it by hand instead, set one environment variable per provider. No code changes required.

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

# OpenAI (SDK, OpenAI-compatible clients) — /v1 REQUIRED:
export OPENAI_BASE_URL=http://localhost:7747/v1

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

# xAI / Grok — /v1 REQUIRED:
export XAI_BASE_URL=http://localhost:7745/v1

# NVIDIA NIM — /v1 REQUIRED:
export NVIDIA_BASE_URL=http://localhost:7744/v1

Your agent still talks to the same SDK, same request and response format. Every request passes through the multi-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.

OpenAI Codex CLI: a bare OPENAI_BASE_URL does not route Codex — it reads its provider from ~/.codex/config.toml, not the environment. Add (or let Connect Agent merge in) a Crawdad provider:

model_provider        = "crawdad"
preferred_auth_method = "apikey"

[model_providers.crawdad]
name     = "Crawdad"
base_url = "http://localhost:7747/v1"
env_key  = "OPENAI_API_KEY"
wire_api = "chat"

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 Connect Agent screen discovers the agents already running on your machine and offers a one-click, consented, persistent Connect for each; the connection confirms 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 the installed version
curl http://127.0.0.1:7749/v1/health  # internal control port
# {"status":"ok","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.

Modes: recording vs blocking

A fresh install is observe-first: Crawdad inspects and scores every call and records what it finds, but it does not block, and it makes no changes to your operating system. Two independent axes control that, both off by default:

• DetectionEnforcement — Observe (record only) or Enforce (block on detection). Turn blocking on with crawdad arm (off with crawdad disarm) or from the dashboard's Protection Mode screen.
• EnforcementMode — Monitor (no OS changes) or Enforce (a persistent OS-level default-deny egress lock binds all agent egress to Crawdad).

The header mode pill tells you the honest posture at a glance and never shows green while recording-only: neutral Monitoring when it is recording, accent/green Enforcing once detections block. Clicking it opens the Protection Mode screen. Detection strictness presets (Maximum / Standard / Reduced / Paused) and per-layer sensitivity live in Settings; Paused keeps detection and audit running while suppressing blocking, useful when something legitimate is being blocked and you need to ship.

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 stay on your machine by default. 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

See the full system requirements — footprint, latency, and everything you need to install and connect.

The production scan path runs at 99.8% detection and 0.09% false-positive rate (1/1,172) 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 (FP32, ~568 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 on-device guarantee that raw content stays local.

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

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

# OpenAI (GPT, OpenAI SDK) — /v1 required
export OPENAI_BASE_URL=http://localhost:7747/v1

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