How do I integrate Clampd with my AI agent?

Wrap your client in one line. For OpenAI, Anthropic, LangChain, CrewAI, or Google ADK, import the Clampd SDK, pass your existing client into the wrapper, and every tool call goes through the Clampd gateway. No agent loop rewrite required.

Which frameworks and providers does Clampd support?

OpenAI, Anthropic, LangChain, CrewAI, Google ADK, and the Model Context Protocol (MCP). SDKs are available in Python, TypeScript, Go, and Java. The MCP proxy supports any MCP server transparently — Claude Desktop today, plus any other MCP client.

Do I need to rewrite my agent loop to use Clampd?

No. The SDK wraps your existing client. Your agent loop, prompts, and tool definitions stay the same. Clampd intercepts at the tool-call boundary, so it adds enforcement without forcing you to restructure how you call the LLM.

How do scope tokens replace long-lived credentials?

Clampd mints a short-lived Ed25519-signed token for each tool call, bound to (tool, params) via SHA-256, verified by the downstream tool through a JWKS-distributed public key. The agent never holds the real database password or API key.

Can Clampd secure MCP servers?

Yes. Run any MCP server behind the Clampd MCP proxy. It enforces descriptor hashing for rug-pull prevention, scope tokens, prompt-injection scanning, and session correlation across the 9-stage gateway. Works with Claude Desktop and any MCP client.

How do I configure detection rules and thresholds?

Detection rules ship with sensible defaults across 12 tool-call categories. Per-rule weights, thresholds, and the LLM-as-judge gray-zone bounds (default 0.2 / 0.75) are configurable through the dashboard policy editor, environment variables, or the policy YAML mounted at deploy time.

Clampd Docs — AI Agent Firewall SDK Reference

Python TypeScript CLI Architecture

Python SDK

Python Quickstart

1-line integration. The minimal OpenAI example below is here so this tab is self-contained. For Anthropic, LangChain, Google ADK, CrewAI, multi-agent identity, response inspection, streaming, and MCP proxy examples, see /sdk.

Guard OpenAI tool calls

 python
import clampd
from openai import OpenAI

client = clampd.openai(OpenAI(), agent_id="my-agent", secret="ags_...")
# That's it. All tool calls now go through the security pipeline.
response = client.chat.completions.create(model="gpt-4o", messages=messages, tools=tools)

→ Full Python SDK reference and 10 more framework examples on /sdk

TypeScript SDK

TypeScript Quickstart

1-line integration. The minimal OpenAI example below is here so this tab is self-contained. For Anthropic, function wrapping, response inspection, multi-agent identity, streaming, and MCP proxy examples, see /sdk.

Guard OpenAI tool calls

 typescript
import clampd from "@clampd/sdk";

const wrapped = clampd.openai(client, { agentId: "my-agent", secret: "ags_..." });
// All tool calls now verified through the security pipeline

→ Full TypeScript SDK reference and 8 more examples on /sdk

CLI Tool

clampd CLI

A standalone CLI for managing your Clampd cluster from the terminal. Inspect agents, trigger kills, import policies, stream audit logs, run compliance reports, and monitor everything with a live TUI dashboard.

Download now: Pre-built binaries for Linux (x86_64, ARM64) and Windows available on the Setup page. macOS: build from source with cargo install.

Commands

Command	Description
`clampd agent list`	List all registered agents with state and risk
`clampd kill <agent-id>`	Emergency kill switch
`clampd policy list`	Show active policies
`clampd watch`	Live TUI dashboard - real-time monitoring
`clampd demo`	Run live demo with real threat detection

Agent Management

 bash
# List all agents
$ clampd agent list
┌──────────┬──────────────┬────────┬──────┬───────────┐
│ ID       │ Name         │ State  │ Risk │ Framework │
├──────────┼──────────────┼────────┼──────┼───────────┤
│ a1b2c3.. │ demo-scout   │ active │ low  │ langchain │
│ d4e5f6.. │ demo-exec    │ active │ med  │ openai    │
│ g7h8i9.. │ attacker-bot │ killed │ high │ custom    │
└──────────┴──────────────┴────────┴──────┴───────────┘

# Kill a compromised agent
$ clampd kill g7h8i9.. --reason "Breach pattern detected"
Kill cascade initiated for agent g7h8i9..
  ✓ Agent terminated across all layers
  ✓ Agent state → killed

Live TUI Dashboard

 terminal
$ clampd watch
╔═ SERVICES ══════════╦═ AGENTS ══════════════════════╗
║ gateway       [OK]  ║ > demo-scout   active  low    ║
║ registry      [OK]  ║   demo-exec    active  med    ║
║ classifier    [OK]  ║   attacker-bot killed  high   ║
║ policy        [OK]  ║                              ║
║ token         [OK]  ║                              ║
╠═ LIVE EVENTS ═══════╩══════════════════════════════╣
║ 14:01:02 demo-scout   access_scoped  scope=read    ║
║ 14:01:03 demo-exec    tool_call api.stripe.charge ║
║ 14:01:04 demo-exec    POLICY_DENY over_budget      ║
║ 14:01:05 attacker-bot KILL_SWITCH breach_detected  ║
╠═ DETAILS ══════════════════════════════════════════╣
║ Selected: demo-scout | State: active               ║
║ Framework: langchain | Boundaries: max_calls=100   ║
╚════════════════════════════════════════════════════╝

Demo Mode

 bash
# Run breach scenario - registers real agents, sends real requests
# through the full pipeline, triggers real kill cascades
$ clampd demo --scenario breach

Starting demo scenario: breach
Checking cluster services...
Gateway reachable
Registering demo agents...
Agents ready. Launching TUI + demo events...

# The TUI shows live events as they flow through the pipeline:
# - Safe queries → ALLOW → forwarded to target
# - DROP TABLE / SSRF / reverse shell → BLOCKED by rules engine
# - Repeated violations → automatic kill cascade

Context Management

Manage multiple environments with named contexts - like kubectl config. Each context stores an endpoint, org ID, and credentials. Switch instantly between local, staging, and production.

 bash
# Initialize config
$ clampd config init
Config written to ~/.clampd/config.toml
Default context 'local' created.

# Add a production context
$ clampd context add prod \
    --endpoint https://api.clampd.dev \
    --gateway-url https://gateway.clampd.dev \
    --set-org-id a1234567-... \
    --set-api-token ag_live_xxx

# List contexts (* = active)
$ clampd context list
     NAME            DASHBOARD                                GATEWAY                        ORG_ID
 *   local           http://127.0.0.1:3001                    http://127.0.0.1:8080          (not set)
     prod            https://api.clampd.dev                   https://gateway.clampd.dev     a1234567-...
     staging         https://staging.internal:3001             https://staging.internal:8080   c9999999-...

# Switch context
$ clampd context use prod
Switched to context 'prod'.

# All commands now target prod
$ clampd agent list
$ clampd cluster status

Configuration File

Stored at ~/.clampd/config.toml. Contexts replace the old flat config - existing configs auto-migrate.

 ~/.clampd/config.toml
current_context = "local"

# Local development
[[contexts]]
name          = "local"
dashboard_url = "http://127.0.0.1:3001"
gateway_url   = "http://127.0.0.1:8080"
org_id        = ""
api_token     = ""
license_token = ""

# Production (SaaS or self-hosted)
[[contexts]]
name          = "prod"
dashboard_url = "https://api.clampd.dev"
gateway_url   = "https://gateway.clampd.dev"
org_id        = "a1234567-1234-1234-1234-123456789012"
api_token     = "ag_live_xxx"
license_token = "eyJ..."

# Environment variables override the active context
# CLAMPD_ORG_ID, CLAMPD_API_TOKEN, CLAMPD_DASHBOARD_URL, CLAMPD_GATEWAY_URL

clampd-guard (Claude Code & Cursor)

A standalone binary that hooks into Claude Code and Cursor as a PreToolUse/PostToolUse guard. Every tool call is verified against your Clampd gateway before execution. 3.2MB binary, <100ms per check.

 bash
# Install
curl -fsSL https://clampd.dev/install-guard.sh | sh

# One-time setup (installs hooks automatically)
clampd-guard setup \
  --url https://your-gateway:8080 \
  --key your-api-key \
  --agent your-agent-id \
  --secret your-agent-secret

# Sync tools for dashboard visibility
clampd-guard sync

What it does:

PreToolUse - Blocks Bash commands, file writes, web fetches before they execute
PostToolUse - Scans tool output for PII, secrets, sensitive data
MCP discovery - Finds all MCP servers in Claude Code and Cursor configs
Managed config - Security teams push /etc/clampd/guard.json via MDM

Architecture

How Clampd Works

A multi-stage runtime security layer sits between your agents and their tools. Every tool call is authenticated, classified, policy-checked, and audited.

API Reference

Interactive API documentation is available at your Dashboard API:

api.clampd.dev/documentation

┌─────────────────┐     ┌──────────────────────────────────────────────────┐     ┌──────────────┐
│  LLM / Agent    │────▶│            Clampd Security Pipeline               │────▶│  Your Tool   │
│  (LangChain,    │     │                                                  │     │  (DB, API,   │
│   ADK, MCP)     │◀────│  Authenticate → Classify → Evaluate → Audit      │◀────│   File, MCP) │
└─────────────────┘     │  <25ms p95 latency                               │     └──────────────┘
                        └──────────────────────────────────────────────────┘

Detection Engine: Tiered Evaluation (L0–L4)

Inside ag-intent, every tool call is evaluated by a five-layer pipeline. Each layer either short-circuits with a verdict or hands a richer feature vector to the next. The output of the last layer feeds the score and decision step that emits Allow, Deny, or Allow-with-token.

The pipeline is intentionally tiered cheap to expensive. Microsecond-level filters run first so that the vast majority of benign traffic never reaches the heavier rule, dictionary, behavioural, or judge stages. Only ambiguous cases climb the stack.

Some layer details are not published. Adversarial resilience benefits from a less-mappable surface, so L0 and L3 internals are deliberately withheld.

    ┌──────────────────────────────────────────────────┐
    │  Tool call arrives at ag-intent                  │
    │  inputs: tool descriptor + params + session      │
    └────────────────────────┬─────────────────────────┘
                             │
                             ▼
    ┌──────────────────────────────────────────────────┐
    │  L0  Fast-path filter                            │
    │  Pre-filter that rejects clearly-benign calls    │
    │  in microseconds. Implementation details         │
    │  proprietary.                                    │
    └────────────────────────┬─────────────────────────┘
                             │
                             ▼
    ┌──────────────────────────────────────────────────┐
    │  L1  Rule engine                                 │
    │  264 detection rules across 12 categories.       │
    │  See /products for the public rule list.         │
    └────────────────────────┬─────────────────────────┘
                             │
                             ▼
    ┌──────────────────────────────────────────────────┐
    │  L2  Dictionary scan                             │
    │  Token-level scan against malicious-phrase and   │
    │  soft-injection dictionaries.                    │
    └────────────────────────┬─────────────────────────┘
                             │
                             ▼
    ┌──────────────────────────────────────────────────┐
    │  L3  Behavioural signals          [PROPRIETARY]  │
    │  Session correlation across 16 patterns,         │
    │  cross-agent flags, anomaly detectors.           │
    │  Internals withheld for adversarial resilience.  │
    └────────────────────────┬─────────────────────────┘
                             │
                             ▼
    ┌──────────────────────────────────────────────────┐
    │  L4  Normalize + LLM-as-Judge (escalation)       │
    │  Encoding pipeline plus judge invocation when    │
    │  signals are ambiguous. Public thresholds:       │
    │  low 0.2  /  high 0.75.                          │
    └────────────────────────┬─────────────────────────┘
                             │
                             ▼
    ┌──────────────────────────────────────────────────┐
    │  Score and decision                              │
    │  Allow   ·   Deny   ·   Allow-with-token         │
    │  Typically 12.3 ms p50 end-to-end.               │
    └──────────────────────────────────────────────────┘

For per-rule details see the rules reference below. For scoring math, see the source under BSL-1.1.

Pipeline Traces

Real Pipeline Output

Actual log output from Docker. See exactly what happens when a request flows through the proxy.

Blocked request - DROP TABLE users

 pipeline trace
[classify]   Rule matched, tool=database.query
[classify]   Intent classified: risk=high, classification=Malicious
[policy]     Policy evaluated: agent=b0000000..., action=Deny
[audit]      Event logged (1 event)

Allowed request - SELECT name FROM users

 pipeline trace
[classify]   Intent classified: risk=low, classification=Safe
[policy]     Policy evaluated: action=Allow
[scope]      Least-privilege access applied
[gateway]    Downstream responded: status=200, latency=10ms
[audit]      Event logged (1 event)

Rules Engine

What Gets Blocked

The 264 detection rules across 12 categories cover destructive SQL, credential access, SSRF and cloud metadata probing, injection attacks (SQL, NoSQL, LDAP, SSTI), prompt injection, PII exfiltration, shell exploits, XSS / path traversal, and more. Region-specific PII detection covers 20 languages including Aadhaar, PAN, NRIC, and other locale identifiers. Risk thresholds are configurable. For the full rule catalogue with examples and risk levels, see /features and /products.

Audit Trail

Audit Log

Every event is recorded. Query your audit trail with standard SQL.

 sql
SELECT tool_name, blocked, assessed_risk, denial_reason
FROM audit_logs LIMIT 8

tool_name	blocked	assessed_risk	denial_reason
database.query	true	high	destructive SQL
database.query	false	low
file.read	true	high	path traversal
file.read	false	low
http.fetch	true	high	SSRF detected
http.fetch	false	low
shell.exec	true	critical	dangerous command
shell.exec	false	low

Deployment

Deployment Options

Hosted at app.clampd.dev with no infrastructure to manage. Self-hosted via Docker Compose for the full 9-service pipeline. Kubernetes / Helm charts coming soon. Air-gapped install supported after one-time license activation. For complete install steps, license activation, compose file links, and air-gapped notes, see /setup.

Prometheus Metrics

ag-gateway exposes a /metrics endpoint in Prometheus exposition format. Scrape it with any Prometheus-compatible tool.

 metrics
agentguard_requests_total, agentguard_requests_denied_total, agentguard_requests_allowed_total,
agentguard_requests_flagged_total, agentguard_circuit_breaker_open_total, agentguard_cache_hits_total,
agentguard_latency_sum_us, agentguard_latency_count

Tool Integration

Validating Micro-Tokens

When Clampd approves a tool call, it mints a short-lived, single-use micro-token and forwards it to your tool service via the Authorization: Bearer <token> header. Your tool service should validate this token before executing any action.

Token Properties

Property	Description
`sub`	Agent ID that initiated the tool call
`scope`	Space-separated list of scopes the agent is allowed (e.g. `db:read`)
`exp`	Expiry timestamp - tokens expire in 30 seconds
`jti`	Unique token ID - each token can only be used once
`ag:tool_binding`	Hash binding the token to a specific tool descriptor
`ag:session_id`	Session ID (optional) for correlating calls within a session
`ag:trust_level`	Trust level (optional) - present when operating in degraded mode

Validation via Introspect API

The recommended approach is to call the Clampd Introspect endpoint, which verifies the signature, checks expiry, enforces single-use, and confirms the agent is not on the deny list - all in one call.

 pseudo-code
# In your tool service - before executing the tool action

def handle_tool_request(request):
    token = request.headers["Authorization"].removeprefix("Bearer ")

    # Call Clampd Introspect endpoint
    result = clampd_client.introspect(token)

    if not result.active:
        return error(403, "Token rejected: " + result.reason)

    # Check that the token grants the required scope
    if "db:read" not in result.scope.split():
        return error(403, "Insufficient scope")

    # Token is valid, single-use enforced, agent is active
    return execute_tool(request)

Introspect Response

Field	Type	Description
`active`	boolean	`true` if the token is valid and consumable
`sub`	string	Agent ID
`scope`	string	Space-separated scopes
`exp`	integer	Expiry (Unix timestamp)
`tool_binding`	string	Tool descriptor binding hash
`reason`	string?	Why the token was rejected (only when `active` is `false`)

Tokens are single-use: once introspected, the nonce is consumed and the same token cannot be used again. If your tool service does not call Introspect, the token expires automatically after 30 seconds.

Security Testing

External Security Testing

Validate your Clampd deployment with built-in testing tools, external red team frameworks, and community payload lists. Run attacks against your own cluster to verify every rule fires correctly.

Built-in Testing

The clampd test CLI command fires a suite of attack payloads against your gateway and reports which were blocked, flagged, or allowed.

Flag	Description
`--gateway <url>`	Gateway URL (default: `http://localhost:8080`)
`--attacks <category\|all>`	Attack categories to run: `sqli`, `xss`, `ssrf`, `shell`, `traversal`, `injection`, or `all`
`--json`	Output results as JSON (for CI pipelines)
`--watch`	Continuous mode. Re-run tests on an interval
`--interval <seconds>`	Interval between watch runs (default: 60)
`--exit-on-fail`	Exit with non-zero code if any attack is not blocked (CI gate)

bash

# Run all built-in attacks, output JSON, fail if any attack gets through
clampd test --gateway http://localhost:8080 --attacks all --json --exit-on-fail

You can also use the Red Team Live tab in the Playground to run attacks interactively from the browser.

External Red Team Tools

Clampd endpoints are standard HTTP. Any security testing tool that can send POST requests can target them. Below are well-known frameworks and payload sources that work out of the box.

Tool	Install	What It Tests	Clampd Endpoint
Promptfoo	`npm i -g promptfoo`	80+ attack plugins, encoding evasion	`/v1/proxy`, `/v1/scan-input`
Garak (NVIDIA)	`pip install garak`	Encoding probes, jailbreaks, DAN attacks	`/v1/scan-input`
PyRIT (Microsoft)	`pip install pyrit`	Multi-step attack chains, red teaming	`/v1/proxy`
SecLists	`github.com/danielmiessler/SecLists`	1000+ SQLi, XSS, LFI payloads	`/v1/scan-input`
PayloadBox	`github.com/payloadbox`	Categorized injection payloads	`/v1/scan-input`

Example: Promptfoo Config for Clampd

Save this as promptfooconfig.yaml and run promptfoo redteam run to fire 50 adversarial probes at your gateway.

 yaml
targets:
  - id: http
    config:
      url: 'http://localhost:8080/v1/scan-input'
      method: 'POST'
      headers:
        'Content-Type': 'application/json'
        'X-AG-Key': '${CLAMPD_API_KEY}'
        'Authorization': 'Bearer ${CLAMPD_JWT}'
      body:
        text: '{{prompt}}'
        agent_id: '${CLAMPD_AGENT_ID}'

redteam:
  purpose: 'AI agent tool call security'
  numTests: 50
  plugins:
    - 'prompt-injection'
    - 'sql-injection'
    - 'ssrf'
    - 'shell-injection'
  strategies:
    - 'jailbreak'
    - 'base64'
    - 'rot13'

Example: Garak Config for Clampd

Garak uses a REST generator to target any HTTP endpoint. Save as garak-clampd.yaml and run garak --model_type rest --model_name clampd --config garak-clampd.yaml.

 yaml
# garak-clampd.yaml - REST generator targeting Clampd scan-input
rest:
  uri: 'http://localhost:8080/v1/scan-input'
  method: POST
  headers:
    Content-Type: 'application/json'
    X-AG-Key: '${CLAMPD_API_KEY}'
    Authorization: 'Bearer ${CLAMPD_JWT}'
  body: '{"text": "$prompt", "agent_id": "${CLAMPD_AGENT_ID}"}'
  response_json_field: 'result'

# Run with encoding and jailbreak probes
# garak --model_type rest --model_name clampd --config garak-clampd.yaml \
#   --probes encoding,dan,gcg

Quick Payload Test Script

A minimal bash script to fire payload lists (SecLists, PayloadBox, or your own) at Clampd and report which payloads were not blocked.

 bash
#!/bin/bash
# test-clampd-payloads.sh - fire payload lists at Clampd
GW="${1:-http://localhost:8080}"
KEY="${CLAMPD_API_KEY:-ag_test_acme_2026}"
JWT="${CLAMPD_JWT}"
AGENT="${CLAMPD_AGENT_ID:-b0000001-0004-0000-0000-000000000001}"
FILE="${2:-payloads.txt}"

if [ ! -f "$FILE" ]; then
  echo "Usage: $0 [gateway-url] <payload-file>"
  echo "  e.g. $0 http://localhost:8080 SecLists/Fuzzing/SQLi/quick-SQLi.txt"
  exit 1
fi

passed=0; failed=0; total=0
while IFS= read -r payload; do
  [ -z "$payload" ] && continue
  total=$((total + 1))
  resp=$(curl -s -o /dev/null -w "%{http_code}" \
    -X POST "$GW/v1/scan-input" \
    -H "Content-Type: application/json" \
    -H "X-AG-Key: $KEY" \
    -H "Authorization: Bearer $JWT" \
    -d "{\"text\": $(echo "$payload" | jq -Rs .), \"agent_id\": \"$AGENT\"}")
  if [ "$resp" = "200" ]; then
    echo "MISS [$resp] $payload"
    failed=$((failed + 1))
  else
    passed=$((passed + 1))
  fi
done < "$FILE"

echo ""
echo "Results: $total tested, $passed blocked, $failed missed"
[ "$failed" -gt 0 ] && exit 1 || exit 0

Docs & SDK Reference

Python Quickstart

Guard OpenAI tool calls

TypeScript Quickstart

Guard OpenAI tool calls

clampd CLI

Commands

Agent Management

Live TUI Dashboard

Demo Mode

Context Management

Configuration File

clampd-guard (Claude Code & Cursor)

How Clampd Works

API Reference

Detection Engine: Tiered Evaluation (L0–L4)

Real Pipeline Output

Blocked request - DROP TABLE users

Allowed request - SELECT name FROM users

What Gets Blocked

Audit Log

Deployment Options

Prometheus Metrics

Validating Micro-Tokens

Token Properties

Validation via Introspect API

Introspect Response

External Security Testing

Built-in Testing

External Red Team Tools

Example: Promptfoo Config for Clampd

Example: Garak Config for Clampd

Quick Payload Test Script