Documentation

Everything you need to deploy Clausgap, write policies, and integrate your AI agents.

How Clausgap works

Clausgap sits between your AI agents and every tool or API they touch. It intercepts each request, evaluates it against your policy bundle, and either allows it, denies it, rate-limits it, or holds it in a multi-party escrow queue pending human approval.

Agent  (SDK: X-Clausgap-Context HMAC header)
       (Keyless: JWT Bearer / API key / IP-CIDR — no code changes)
  │
  ▼
clausgap-proxy ──┬──► :8443 HTTP listener  ──► REST APIs / tools
                 ├──► :5433 PG listener    ──► PostgreSQL / Redshift
                 └──► :3000 MCP listener   ──► MCP tool servers

  │  Local bundle evaluation (no network round-trip on hot path)
  │
  ├─ ALLOW  → forward request, return response
  ├─ DENY   → 403 / SQL error / JSON-RPC error
  ├─ ESCROW → 423 Locked + {escrow_id}  (agent polls; M-of-N voting)
  └─ RATE   → 429 Too Many Requests

  ↕  Async (bundle sync, event drain, escrow state)
Control Plane API  (/v1/...)

Policy evaluation happens inside the proxy using a locally cached, Ed25519-signed bundle — so there is no control-plane round-trip on the hot path. Bundles are refreshed from the control plane every 30 seconds (configurable). Agent identity is resolved from the X-Clausgap-Context HMAC header (SDK mode) or, in keyless mode, from a JWT Bearer token, a registered API key, or source IP/CIDR — no agent code changes required.

Quickstart

Create a workspace, then four steps take you to a policy enforcing your agent's traffic. The Get started page in the dashboard tracks the same steps and completes each one by itself when it happens — a proxy connects, a request arrives, a policy decides one.

routes:
  # HTTP upstream — proxied as-is
  - tool: "web_search"
    upstream: "http://search-service:8080"
    methods: ["GET"]

  - tool: "file_write"
    upstream: "http://fs-service:9000"
    methods: ["POST", "PUT", "DELETE"]

  # MCP / JSON-RPC server — tools auto-discovered on startup
  - tool: "mcp_tools"
    upstream: "http://mcp-server:5000/"
    methods: ["POST"]
    protocol: "jsonrpc"
    discover: true

tenant_id: "$CLAUSGAP_TENANT_ID"
log:
  level: "info"

control_plane:
  url:          "https://api.clausgap.dev"
  api_key:      "$CLAUSGAP_API_KEY"
  poll_interval: "30s"               # How often to pull policy bundle

listeners:
  # HTTP listener — governs REST API / tool calls
  - protocol: http
    addr: ":8443"
    # advertise_addr: "agents.example.com:443"   # Where agents connect, if not addr (see below)
    http:
      routes_file: "./routes.yaml"
      hmac_secret: "$HMAC_SECRET"    # Shared with your agent SDK

  # Uncomment to add PostgreSQL governance:
  # - protocol: pg
  #   addr: ":5433"
  #   pg:
  #     upstream_host:   "postgres"
  #     upstream_port:   5432
  #     upstream_dbname: "mydb"

# Run the binary
HMAC_SECRET=my-secret CLAUSGAP_API_KEY=clk_free.xxx \
  clausgap-proxy -config proxy.yaml

# Or with Docker
docker run -d --name clausgap-proxy \
  -p 8443:8443 \
  -e HMAC_SECRET=my-secret \
  -e CLAUSGAP_API_KEY=clk_free.xxx \
  -e CLAUSGAP_TENANT_ID=my-org \
  -v $(pwd)/routes.yaml:/etc/clausgap/routes.yaml \
  -v $(pwd)/proxy.yaml:/etc/clausgap/proxy.yaml \
  ghcr.io/clausgap/clausgap-proxy:latest

securityContext:
  runAsNonRoot: true
  runAsUser: 65532
  runAsGroup: 65532
  allowPrivilegeEscalation: false
  readOnlyRootFilesystem: true   # with an emptyDir mounted at /tmp
  capabilities: { drop: ["ALL"] }
  seccompProfile: { type: RuntimeDefault }

import base64, hashlib, hmac, json, secrets, time, requests

HMAC_SECRET = "my-secret"   # matches proxy.yaml hmac_secret
PROXY_URL   = "http://localhost:8443"

def make_context(method, target, body, agent_role, agent_id, session_id, confidence=1.0):
    """A v2 context header, signed for exactly this request and usable once."""
    payload = json.dumps({
        "agent_role": agent_role,
        "agent_id":   agent_id,
        "session_id": session_id,
        "confidence": confidence,
        "step_index": 0,
        "model_id":   "gpt-4",
    }).encode()
    b64   = base64.b64encode(payload).decode()
    ts    = str(int(time.time()))
    nonce = secrets.token_hex(16)
    message = "\n".join([
        "clausgap-context-v2", ts, nonce, method.upper(), target,
        hashlib.sha256(body).hexdigest(), b64,
    ])
    sig = hmac.new(HMAC_SECRET.encode(), message.encode(), hashlib.sha256).hexdigest()
    return f"v2.{b64}.{sig}.{ts}.{nonce}"

# Sign the exact path + query you send — the header is only valid for it.
target = "/web_search?q=latest+sales+report"
resp = requests.get(
    PROXY_URL + target,
    headers={"X-Clausgap-Context": make_context("GET", target, b"", "my_agent", "a-1", "sess-001", 0.95)},
)

if resp.status_code == 200:
    print("Allowed:", resp.json())
elif resp.status_code == 403:
    print("Denied by policy")
elif resp.status_code == 423:
    escrow_id = resp.json()["escrow_id"]
    print("Held in escrow — awaiting M-of-N approval:", escrow_id)

policy "my_policy" {
    description = "Describe what this policy controls"

    agent_role  = "my_agent"
    environment = "staging"

    allow call tool "read_data" when method = "GET"
    allow call tool "submit_action"
    deny  call tool "delete_records"

    # Hold dangerous actions for multi-party approval
    escrow when tool = "submit_action" {
        hold_type = "multi_party"
        required_approvals = 2
        notify = ["https://hooks.slack.com/services/T000/B000/approvals"]
    }

    # Hold low-confidence actions for review
    escrow when confidence < 0.7
    rate_limit 10 requests per minute
}

From here: give each agent its own credential (Connecting your identity provider), hold risky actions for approval (Escrow rules), and export evidence an auditor can check offline (Verifying evidence).

Proxy configuration reference

The unified proxy (clausgap-proxy) is configured via a single YAML file. A listeners: array activates one or more protocol listeners sharing a single policy engine and control-plane connection. All string values support $ENV_VAR substitution. See Protocol Reference for per-listener configuration fields.

Health endpoints

/healthz and /readyz are served on the HTTP listener regardless of policy load state. /metrics is served only on the separate metrics server bound to metrics.addr (default :9090), never on the port agents use: it carries agent roles and tool names. Keep that port off public networks.

Routes file

routes.yaml maps tool names (used in policy rules) to upstream services. The proxy routes each inbound request to the matching upstream after policy evaluation.

Policy DSL

Policies are written in the Clausgap DSL — a human-readable, version-controlled configuration language. Each policy file contains one or more policy blocks.

Structure

policy "policy_name" {
    description = "Human-readable description"

    # Required — must match the agent_role in X-Clausgap-Context
    agent_role  = "my_agent"

    # Optional — restrict to a specific environment
    environment = "prod"   # or "staging", "dev"

    # Optional — policy scope for multi-proxy deployments (default: "default")
    scope       = "finance"

    # ... rules ...
}

Tool rules (HTTP proxy)

# Allow / deny by tool name
allow call tool "web_search"
deny  call tool "delete_records"

# Wildcard
allow call tool "*"

# Conditional — only allow GET requests to this tool
allow call tool "read_data" when method = "GET"

Table rules (PG proxy)

# Column-level read control
allow read on table "orders"  columns ["id", "status", "total"]
deny  read on table "users"   columns ["ssn", "credit_card"]

# Blanket table control
allow read on table "products"
deny  write on all tables

# Row-level filter — injected as WHERE clause on every query
filter on table "orders" where "region = 'EMEA'"

Deterministic deny conditions (context_deny)

context_deny enforces hard denials on structured call metadata — SQL operations, table names, and time windows. These rules are deterministic: they do not depend on confidence scores or LLM output and are directly auditable in compliance reviews.

# Deny destructive SQL operations
context_deny operation in (DELETE, DROP, TRUNCATE)

# Deny access to sensitive tables
context_deny table in ("users_pii", "payments", "audit_log")

# Deny outside business hours (UTC)
context_deny time_of_day outside "09:00-17:00"

Escrow rules

Escrow holds the request (423 Locked) until one or more approvers vote, an external condition is met, or a time delay expires. Supports four hold types: manual, multi_party, conditional, and time_delayed.

# Simple manual hold — one approver required
escrow when tool = "send_email"

# Multi-party — M-of-N approvers
escrow when tool = "submit_order" {
    hold_type          = "multi_party"
    required_approvals = 2
    notify             = ["https://hooks.slack.com/services/T.../B.../finance"]
}

# Conditional — released when external webhook confirms
escrow when tool = "deploy" {
    hold_type      = "conditional"
    condition      = "webhook_confirm"
    condition_url  = "https://ci.internal/check"
}

# Manual with custom TTL (seconds)
escrow when tool = "modify_record" {
    hold_type = "manual"
    ttl       = 86400
}

# Time-delayed — auto-releases after the delay unless cancelled
escrow when tool = "bulk_delete" {
    hold_type = "time_delayed"
    ttl       = 3600
}

Rate limiting and budgets

rate_limit 20 requests per minute
rate_limit 100 requests per hour
rate_limit 1000 requests per day
rate_limit 50 requests per session

# Not enforced yet: these compile with a warning and have no effect
cost_budget  5.00    per session       # USD
token_budget 500000  tokens per hour

active_hours "08:00-20:00" timezone "Europe/London"

expires "2027-12-31T23:59:59Z"

Evaluation order

When a request arrives, the proxy evaluates rules in this fixed order. Evaluation short-circuits at the first match. A rate_limit is enforced separately: a call over its limit gets 429.

Injection Defense

Clausgap detects prompt injection and behavioural anomalies before your policy rules even run. All checks run inline, inside the proxy, and are configured in the same DSL as your allow/deny rules.

trigger_source — verify who initiated the call

Pass trigger_source in your SDK context to declare whether the tool call was initiated by a human user, another agent, or the environment (e.g. a retrieved document). Use it in when conditions to restrict sensitive tools to direct user intent only.

# Only allow email when the user — not a retrieved doc — triggered it
allow call tool "send_email" when trigger_source = "user"
deny  call tool "send_email" when trigger_source = "environment"

In the SDK, set triggerSource on each evaluate call. The proxy defaults to "user" when the field is absent.

// TypeScript SDK
await gate.evaluate({
  toolName: "send_email",
  triggerSource: "user",   // "user" | "environment" | "agent"
})

injection_scan — block known attack patterns

Scans tool arguments against a built-in library of prompt injection signatures (instruction overrides, privilege escalation, role impersonation, exfiltration attempts), plus any custom patterns registered for your tenant. Fires before rule matching; a tool can opt out with except injection_scan (below), but no other allow rule bypasses it.

injection_scan action = "deny"

# Opt a trusted tool out of scanning
allow call tool "internal_summariser" except injection_scan

sequence_deny — detect suspicious sequences

Triggers when a tool is called shortly after a specific preceding tool in the same session — a pattern common in exfiltration chains (read data, then immediately send it out). The within window is in seconds.

# Deny any exfil-like tool called within 60 s of a DB read
sequence_deny tools ["send_email", "post_webhook"]
    after ["query_database", "read_file"]
    within 60

velocity_limit — spike detection

Flags sessions where the per-minute call rate spikes above a multiple of the session baseline. Unlike rate_limit (which enforces an absolute cap), velocity detection catches sudden bursts that are anomalous relative to normal behaviour.

# Deny if current-minute rate is 5× the session baseline
# (baseline established after min 10 calls)
velocity_limit spike 5.0 min 10 action = "deny"

Keyless mode (no SDK required)

Keyless mode lets you drop Clausgap in front of any existing agent framework — LangChain, AutoGen, CrewAI, raw tool loops — with zero code changes. The proxy resolves agent identity from the request itself using a priority resolver chain.

Enable keyless mode

# proxy.yaml
listeners:
  - protocol: http
    addr: ":8443"
    http:
      routes_file: "./routes.yaml"
      keyless:
        enabled: true
        mode: "strict"            # "permissive" allows anonymous fallback during migration
        api_key_sources:
          - header: "Authorization"
            prefix: "Bearer "
          - header: "X-API-Key"
        static_roles:
          - source_ip: "10.0.0.0/8"
            agent_role: "internal-agent"
            agent_id:   "internal-01"
        # Optional: enrich audit logs from advisory headers
        supplementary_headers:
          session_id: "X-Conversation-Id"
          agent_id:   "X-Agent-Instance-Id"
        # Optional: extract developer-defined confidence from response body
        confidence:
          source: "body_json"
          path:   "$.confidence"
          trust:  "unverified"   # advisory label: confidence came from an unsigned header/body

Identity trust tiers

Every decision record includes an identity_resolver field that indicates how the agent was identified. The dashboard surfaces this as a trust badge on each event.

JWT providers

Register a provider with POST /v1/keyless/jwt-providers. An audience is required — it must match the aud claim your issuer puts in tokens meant for Clausgap; without it, any token the issuer minted for another application would be accepted. ES256, ES384 and ES512 keys must be on the curve the algorithm names (P-256, P-384, P-521), and the jwks_uri must be a public https URL. claims_mapping names the claim that carries the agent's role (default clausgap_role) and ID (default sub) — tokens from your organisation's identity provider work as they are. Registering a provider with a name or issuer you already registered is a 409. Setting this up end to end — with single sign-on for people too — is covered in Connecting your identity provider.

What reaches your upstream

The proxy removes the agent's Clausgap credentials before forwarding — the X-Clausgap-Context header and whichever header carried a keyless JWT or API key (Authorization, X-API-Key) — so a tool server can never replay them as the agent. To give a tool its own credentials, set upstream_headers on the HTTP listener (see Protocol Reference).

Policy scopes

Scopes let large deployments partition policies across proxy fleets — each proxy receives only the policies it needs. Every policy belongs to one scope (default: "default"). Proxies declare which scopes they subscribe to; the control plane compiles and signs a filtered bundle containing only matching policies. Existing deployments are unaffected — everything continues to use the implicit default scope.

Assign a scope in the policy DSL

policy "pii_guardrail" {
    description = "PII controls for the finance team agents"
    agent_role  = "finance_agent"
    scope       = "finance"   # ← assigns this policy to the "finance" scope

    deny call tool "export_data"
    context_deny table in (customers_pii, ssn_records)
}

The scope field is optional. Omitting it is equivalent to scope = "default".

Subscribe a proxy to scopes

Add a scopes: list to proxy.yaml. The proxy sends this list in every heartbeat and uses it when fetching the bundle from the control plane.

tenant_id: ten_abc123
proxy_id:  finance-proxy

# This proxy only receives policies tagged scope="finance" or scope="default"
scopes:
  - default
  - finance

control_plane:
  url:     https://api.clausgap.dev
  api_key: $CLAUSGAP_API_KEY

listeners:
  - protocol: http
    addr: :8080
    http:
      routes_file: /etc/clausgap/routes.yaml

How it works end-to-end

Evaluate Clausgap

Before connecting anything real, run the evaluations that come with the Clausgap source. Each starts its own local stack with synthetic data, runs scripted checks end to end, and writes a report you can keep as evidence. They're industry-neutral — the same checks run for finance, healthcare and DevOps examples.

./evaluation/kit/run.sh          # fresh kit, every scenario
./evaluation/kit/run.sh --up     # keep it running to explore
./evaluation/approvals/run.sh
./evaluation/evidence/run.sh