Loopers

The AI Firewall for the Agentic Era

Stop runaway loops. Block data exfiltration. Enforce policy. No SDK required.

The Problem

1. Uncontrolled Cost & Runaway Loops
Autonomous AI agents are expensive when running unsupervised. A single stuck retry loop, recursive reasoning stall, or cascade failure can burn hundreds of dollars in API credits within minutes. Upstream provider dashboards only give post-hoc metrics and alerts after the damage has already hit your card. Loopers intercepts traffic in real time and cuts off spending before the bill is generated.

2. Runtime Tool Poisoning & Data Exfiltration
Autonomous agents ingest external web pages, parse tool responses, and execute commands. A compromised MCP server, poisoned tool response, or indirect prompt injection can turn your agent into an exfiltration vector. Outbound LLM completions frequently leak credentials, PII, or internal network IPs back to untrusted contexts. Without a runtime firewall inspecting bidirectional traffic, agents operate completely unshielded.

3. Lack of Deterministic Policy Governance
As agent systems scale, relying on prompt instructions for safety and operational boundaries fails. Safety directives placed in system prompts can be overridden by jailbreaks or forgotten across long context windows. Loopers introduces a deterministic, stateful enforcement layer: declarative policies that quarantine, block, mutate, or escalate live requests at the network boundary.

Origins & Authors

Loopers is created and actively maintained by Varad Khoriya and Mayank Agrawal (part of the Loopers organization).

The project was born when an autonomous test agent got stuck in a recursive loop and ran up an unexpected bill during local development. After analyzing the root cause, it became clear that major AI platforms only offer passive telemetry rather than active circuit breakers. We built Loopers to establish an open-source, bare-metal firewall standard for autonomous agent systems.

Have questions, suggestions, or need help integrating? Join the community on GitHub Discussions or submit an issue on GitHub Issues.

AI Agents & LLMs: See AGENT_README.md for dense machine-readable context and configuration schemas.

What Loopers Is — and Is Not

Loopers is a stateful, runtime security firewall for autonomous AI agents.
It is not an AI gateway, model router, prompt management platform, or agent orchestration framework.

The Firewall Difference

How It Works

Architecture Overview

┌──────────────────────────────────────────────────────────────────────────┐
│                             Agent Runtime                                │
│       (Aider / OpenHands / Claude Code / Custom Agent / Python SDK)      │
└────────────────────────────────────┬─────────────────────────────────────┘
                                     │ HTTP (e.g., OPENAI_BASE_URL)
                                     ▼
┌──────────────────────────────────────────────────────────────────────────┐
│                        Loopers Firewall (:8080)                          │
│                                                                          │
│  [1. Key Auth & DPoP] ──► [2. Risk Score & Quarantine Gate]              │
│            │                                                             │
│  [3. Syntactic Normalizer] ──► [4. Pre-Call Budget Lease]                │
│            │                                                             │
│  [5. Policy Engine & FSM] ──► [6. Multi-Engine Loop Detector]            │
│            │                                                             │
│  [7. Upstream Provider Proxy] ──► [8. Outbound DLP & SSE Cutoff]         │
│            │                                                             │
│  [9. Cost Reconcile & Risk Update]                                       │
│                                                                          │
│  Admin Server (:9090): /metrics (Prometheus) | /health                   │
│  Telemetry: OpenTelemetry Traces (OTLP gRPC/HTTP) | HMAC Webhooks        │
└───────────────────┬──────────────────────────────────┬───────────────────┘
                    │                                  │
                    ▼                                  ▼
          ┌───────────────────┐              ┌───────────────────┐
          │     Redis 7+      │              │ Upstream Provider │
          │ (Atomic Leases,   │              │ (OpenAI, Anthropic│
          │  Risk Scores,     │              │  Gemini, Bedrock, │
          │  FSM Session State│              │  Groq, Ollama...) │
          │  Quarantine Keys) │              └───────────────────┘
          └───────────────────┘

Request Lifecycle

1. Key Authentication & DPoP Check: The agent request arrives with a Loopers proxy key (lp-...). Loopers verifies the HMAC-SHA256 hash against Redis. If DPoP is configured, proof-of-possession is validated against the sender's public key.
2. Quarantine & Risk Profile Gate: Checks the agent's persistent behavioral risk score. If the score exceeds the quarantine threshold (default: 75), requests are rejected with 403 Forbidden. If permanently blocked (score > 90), traffic is dropped.
3. Layer 3 Syntactic Normalization: Inbound prompt content is processed through the 5-stage syntactic normalization pipeline (internal/syntactic), resolving Unicode homoglyphs (Cyrillic, Greek, Math Bold), stripping zero-width/bidi runes, recursively decoding nested Base64/URL percent escapes, and collapsing delimited tokens (i.g.n.o.r.e). Both raw and canonical normalized_prompt are exposed to the policy engine.
4. Pre-Call Atomic Budget Lease: Loopers calculates the maximum estimated cost using model rates from pricing.yaml and atomically reserves this quota in Redis across minute, hourly, daily, weekly, and monthly sliding windows. If limits are reached, the call is blocked before hitting the provider.
5. Policy Engine & FSM Evaluation: Evaluates Open Policy Agent (OPA) Rego rules and declarative YAML Policy Cards against canonical normalized inputs. Validates session state transitions, computes multi-turn conversation drift against initial session anchor goals, and checks tool sequences. If an escalate policy triggers, Loopers suspends the live HTTP connection and awaits human/admin approval via Redis Pub/Sub.
6. Multi-Engine Loop Detection: Evaluates the request against session history using bi-gram Jaccard similarity, request velocity, and SimHash Hamming distance to detect stuck reasoning or recursive loops.
7. Upstream Request Forwarding: Injects the actual upstream provider key (from X-Loopers-Provider-Key or configuration) and forwards the sanitized payload to the LLM provider. The Loopers proxy key is never sent upstream.
8. Outbound Semantic DLP & Mid-Stream SSE Cutoff: As response tokens stream back, Loopers runs a multi-layer DLP inspection to mask PII, redact internal IPs, or sever the connection if secrets are leaked. If a budget cap is breached mid-generation, the SSE stream is cut off immediately.
9. Reconciliation & Telemetry: Reconciles the actual token usage reported by the provider against the estimated lease, releasing unspent funds back to the budget window. Records metrics to Prometheus, spans to OpenTelemetry, and updates the agent's risk profile.

Core Capabilities

• Multi-Engine Runaway Loop Termination: Detects and terminates repetitive reasoning and execution loops using three distinct algorithms:
  • Fingerprint Engine: Bi-Gram Jaccard similarity detection for repetitive prompts.
  • Velocity Engine: Sliding window requests-per-second (RPS) surge limiter.
  • Stall Engine: SimHash Hamming distance analysis to catch low-diversity semantic output stalls.
• Multi-Turn Conversation Drift Detection & Goal Hijacking Protection: Defends against gradual crescent context divergence and sudden prompt injection goal hijacks across multi-turn sessions. Persists an immutable session anchor ($T_1$) in Redis and calculates weighted containment similarity ($75%$ anchor grounding + $25%$ immediate turn continuity) using trigram FNV-1a hashing and English stopword normalization. Proactively terminates diverged requests locally before token consumption.
• Persistent Agent Risk Identity: Tracks behavioral history across sessions in Redis with cumulative risk scoring (0–100), automated time-bounded quarantines (e.g., 1 hour), taint flags (secret_accessed), and risk decay over time.
• Outbound Semantic DLP Gate: Real-time scrubbing of PII (emails, Luhn-validated credit cards, US SSNs, phone numbers), masking of internal network addresses (RFC 1918 IPs, .internal hostnames), and quarantine lockouts on secret leaks (AWS, OpenAI, GitHub tokens, private keys) across both JSON and streaming SSE responses.
• Tool Response Sanitization & Injection Wall: Scans outbound tool responses, normalizes Unicode, strips zero-width obfuscation characters, and blocks path traversal attempts (../) and indirect prompt injection patterns.
• 5-Outcome Policy Action Engine: Declarative OPA/Rego policy engine supporting five distinct actions:
  • allow: Passes request through to the upstream provider.
  • deny: Rejects the request with a structured error payload.
  • escalate: Suspends live HTTP request and waits up to 60s for external human approval via Redis Pub/Sub.
  • quarantine: Freezes the agent key in Redis across all endpoints for a defined lockout duration.
  • transform: Mutates payload fields (e.g., redactions, parameter replacements) in-flight.
• Deterministic FSM Tool Sequencing: Enforces valid state machine transitions on agent tool execution (e.g., requiring dry_run_command before allowing destructive execute_bash calls).
• Atomic Cost Governance: Multi-window budget limits (minute, hourly, daily, weekly, monthly) enforced atomically with zero budget over-charge guarantee.
• Mid-Stream SSE Cutoff: Actively parses and counts streaming Server-Sent Events (SSE) tokens chunk-by-chunk, severing the HTTP stream mid-flight the millisecond a budget ceiling is reached.
• DPoP / Zero-Trust Security Protocol (ZSP): RFC 9449 Demonstration of Proof-of-Possession for cryptographic agent identity verification, preventing token replay attacks.
• Shadow Mode: Operates the firewall in non-blocking observation mode (server.shadow_mode: true) to audit policies against live traffic without impacting production workflows.
• MCP Blast Radius Limiter: Restricts the maximum number of distinct Model Context Protocol (MCP) servers and tools an agent session can bind to, preventing privilege escalation.
• Model Overrides & Header Rewriting: Transparently rewrite models or remap target endpoints on the fly using X-Loopers-Model-Override and X-Loopers-Model-Map headers without modifying agent codebases.
• Offline Trace Verification (loopers verify): Validates past execution trace logs against current policy cards offline, providing verifiable compliance reporting for CI/CD gates.
• Self-Correcting Error Payloads: Returns structured, machine-actionable error messages on policy denials and blocks, allowing autonomous agents to understand the rejection reason and self-correct on subsequent turns.
• Zero-Storage In-Memory Pass-Through: Provider keys and raw payloads remain strictly in-memory during transit and are never written to disk or persistent databases.

Built-in Security Presets

Loopers includes pre-configured security presets that can be enabled instantly via --presets or in loopers.yaml:

Enable presets on startup:

loopers serve --presets safety,safety_drift,pci,mcp_sandbox

Quickstart

Prerequisites

• Go 1.26.6+ or Docker
• Redis 7+ (required for atomic state and budget governance)

Step 1: Install Loopers

# Via Homebrew (macOS / Linux)
brew install cursed-me/tap/loopers

# Via Docker
docker pull ghcr.io/try-loopers/loopers:latest

# Build from Source
git clone https://github.com/try-loopers/loopers-oss.git
cd loopers-oss
go install ./cmd/loopers

Step 2: Initialize Configuration & Start Redis

# Start local Redis instance
docker run -d --name loopers-redis -p 6379:6379 redis:7-alpine

# Initialize Loopers configuration wizard (creates loopers.yaml and docker-compose.yml)
loopers init

# Run system diagnostic checks
loopers doctor

Note: For native installs, ensure the pricing.yaml file from the repository root is present in your working directory, as Loopers requires it at startup.

Step 3: Create a Proxy Key

loopers keys create --name dev-agent --provider openai

Note: This generates a raw proxy key (e.g. lp-a1b2c3d4...) and its SHA-256 hash. Save the raw key immediately.

Step 4: Configure Budget Limits

# Set hourly and daily spending limits on the key hash
loopers budget set <KEY_HASH> --daily 5.00 --hourly 1.00

# Verify current budget allocations
loopers budget status <KEY_HASH>

Step 5: Start the Firewall

# Run in development mode
SERVER_INSECURE_DEV=true loopers serve --presets safety

# 1. Start Redis cache dependency
docker-compose up -d redis

# 2. Run the Loopers firewall locally
SERVER_INSECURE_DEV=true loopers serve --presets safety

[!WARNING] SERVER_INSECURE_DEV=true disables TLS enforcement for local testing. In production environments, configure valid TLS certificates in loopers.yaml.

Step 6: Route Your Agent Traffic

Option A: Transparent CLI Wrapper (Zero Code Changes)

export LOOPERS_PROXY_KEY="lp-your-proxy-key"
export OPENAI_API_KEY="sk-your-actual-provider-key"

# Wrap any agent CLI tool directly. Auto-detection supports:
# aider, openhands, pi, claude, codex, opencode, gemini, dsh, deepseek-harness, deepseek.
# Other tools require setting LOOPERS_PROVIDER explicitly.
loopers exec -- aider

Option B: Base URL Redirection

Point your agent client directly to the Loopers proxy endpoint:

export OPENAI_BASE_URL="http://localhost:8080/lp-your-proxy-key/openai/v1"
export OPENAI_API_KEY="sk-your-actual-provider-key"

aider

Option C: Programmatic Python Integration

from loopers_client import LoopersOpenAI

client = LoopersOpenAI(
    loopers_url="http://localhost:8080",
    loopers_key="lp-your-proxy-key",
    provider_key="sk-your-actual-provider-key",
    session_budget=2.00,  # Cap session spend at $2.00
    max_steps=20          # Terminate if session exceeds 20 turns
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Analyze system logs and report findings."}]
)
print(response.choices[0].message.content)

CLI Reference

Observability & Telemetry

Prometheus Metrics

Loopers runs an isolated admin server on :9090 exposing Prometheus metrics at /metrics:

A pre-configured Grafana Dashboard is provided in the repository for turnkey deployment.

OpenTelemetry Distributed Tracing

Loopers exports standard OpenTelemetry spans via OTLP (gRPC/HTTP) adhering to gen_ai.* semantic conventions. Configure your collector in loopers.yaml:

otel:
  enabled: true
  endpoint: "localhost:4317"
  protocol: "grpc"
  sampling_rate: 1.0

Note: All security enforcement actions (blocks, quarantines, escalations) are traced at 100% fidelity regardless of the configured sampling rate.

Real-Time Webhook Alerts

Configure HMAC-SHA256 signed webhooks to alert external incident systems on security anomalies and budget thresholds:

alerting:
  webhook_url: "https://ops.example.com/alerts"
  webhook_secret: "env:LOOPERS_WEBHOOK_SECRET"
  thresholds:
    - percent: 50
      message: "Agent budget at 50% capacity"
    - percent: 90
      message: "Agent budget near exhaustion — cutoff imminent"

Documentation Index

Explore our comprehensive guides and architectural documentation:

• Budget Governance: Sliding Budget Windows | Per-Session Budgets
• Agent Circuit Breakers: Runaway Loop Detection Guide
• Policy Engine & FSM: OPA Rego & YAML Policy Cards
• Tool Sandboxing: Model Context Protocol (MCP) Setup
• Zero-Code Integration: Agent CLI Wrappers & Environments
• Monitoring: Grafana Dashboards & Prometheus Setup
• CI/CD Compliance: Offline Trace Verification Guide

Contributing

We welcome contributions from the open-source community!

• Bug Reports & Feature Requests: Submit an issue on GitHub Issues.
• Community Discussions: Join conversations on GitHub Discussions.
• Development Workflow: Read our Contributing Guide to learn about code standards, running test suites, and opening pull requests.

License

Loopers is distributed under the MIT License.