# Loopers OSS

> Loopers is the open-source, bare-metal AI Firewall for the Agentic Era. It sits between your application and upstream LLM providers (OpenAI, Anthropic, Gemini, Groq, Bedrock, Azure, Mistral, Cohere, DeepSeek, Together, Ollama, Fireworks, xAI, vLLM, OpenRouter), enforcing pre-call budget limits, runaway loop termination, MCP tool response inspection, persistent agent risk profiles, and real-time outbound semantic DLP protection.

## How Loopers Works (Quick Reference for Agents)

Loopers is a Go binary that proxies and secures AI API calls. Requests from your app go to Loopers first. Loopers checks budgets via Redis, evaluates OPA policies and FSM state, and forwards to the upstream provider. Outbound responses and streaming chunks are inspected in real time for PII and secrets before reaching the client.

**Auth models (two options):**
1. Header auth: Set `Authorization: Bearer lp-xxx` (Loopers proxy key) + `X-Loopers-Provider-Key: YOUR_REAL_KEY`
2. Path auth (zero-code): Embed proxy key in URL — `http://localhost:8080/lp-xxx/openai/v1/chat/completions` — and pass real key as standard `Authorization: Bearer`

**Key environment variables:**
- `SERVER_INSECURE_DEV=true` — required for local dev without TLS certificates
- `SERVER_SHADOW_MODE=true` — run in observation-only mode; logs policy violations without blocking
- `REDIS_ADDR` — Redis address (default: `localhost:6379`)
- `REDIS_PASSWORD` — Redis password
- `SERVER_PORT` — proxy port (default: `8080`)
- `LOOPERS_PROXY_KEY` — used by `loopers exec` to inject proxy key into child process
- `LOOPERS_PROVIDER` — used by `loopers exec` to specify upstream provider (e.g. `openai`, `anthropic`, `openrouter`). Auto-detected for aider, openhands, pi, claude, gemini, codex, opencode, dsh, deepseek-harness, deepseek.

**Core CLI commands:**
- `loopers init` — interactively initialize Loopers AI firewall configuration
- `loopers serve` — starts the Loopers AI firewall runtime server (reads `loopers.yaml`)
- `loopers doctor` — diagnoses firewall config, Redis connectivity, and security engines
- `loopers keys create --name <n> --provider <p>` — creates a proxy key; returns raw key (`lp-xxx`) and hash
- `loopers keys list` — lists all active firewall agent keys
- `loopers keys revoke <hash>` — revokes an agent key
- `loopers budget set <hash> [--minute] [--hourly] [--daily] [--weekly] [--monthly]` — sets atomic spending limits in USD
- `loopers budget status <hash>` — shows real-time spend consumption vs limits
- `loopers exec -- <command>` — wraps a CLI agent process, injecting proxy env vars; supports `--model-override` and `--model-map`. Auto-detects aider, openhands, pi, claude, gemini, codex, opencode, dsh, deepseek-harness, deepseek.
- `loopers verify --trace <path>` — audits agent execution traces offline against Policy Cards, presets (`safety`, `safety_drift`, `pci`, `mcp_sandbox`, `zero_trust`), or Rego rules.

**Supported providers for `--provider` flag:**
`openai`, `anthropic`, `gemini`, `bedrock`, `azure`, `mistral`, `groq`, `cohere`, `deepseek`, `together`, `ollama`, `fireworks`, `xai`, `vllm`, `openrouter`

**Policy engine (OPA/Rego, YAML Cards & Presets):**
All custom policy files must use `package loopers.policy` and define rules evaluated across a 5-outcome decision plane:
- `allow`: Approved & forwarded to upstream.
- `deny`: Immediately rejected. Returns HTTP 403 or JSON-RPC tool error.
- `escalate`: Suspends request to wait for human approval over Redis Pub/Sub (fails closed on timeout).
- `quarantine`: Places key in Redis lockout for a duration (e.g. `quarantine_for: "5m"`), bypassing policy check on subsequent calls.
- `transform`: Mutates prompts, messages, or MCP tool arguments using `mask` or `redact` operations.

*Precedence Resolution:* `deny (5) > quarantine (4) > escalate (3) > transform (2) > allow (1)`. Severity (`critical > warn > info`) resolves ties. Multiple transform rules accumulate field mutations.

Define these security rules in Rego or a single YAML Policy Card (`policy_file: "./policies.yaml"`), or load presets (`presets: ["safety", "safety_drift", "pci", "mcp_sandbox", "zero_trust"]`). All requests across 15+ providers (and generic OpenAI endpoints) are mapped to a unified canonical schema before evaluation. All formats support regular expressions, Deterministic FSM Gating (Trajectory Risk Modeling via `session.state` and transition triggers), Persistent Agent Risk Profiles (`input.agent_risk`), Multi-Turn Conversation Drift Context (`input.session.drift`), and hot-reloads.

**MCP Response Inspection (Indirect Prompt Injection Wall):**
If `mcp.inspector.enabled` is set to true in `loopers.yaml`, Loopers synchronously intercepts outbound `tools/call` response payloads. It normalizes text (stripping zero-width characters) and performs pattern scanning:
1. Indirect prompt injections (e.g., `ignore previous instructions`) and path traversals (`../../etc/passwd`) trigger `transform`, replacing matching strings inline with `[Content removed: security policy]` and injecting the `X-Loopers-Response-Redacted: true` header.
2. Secret leaks (AWS, OpenAI keys, PEM private keys, JWTs, etc.) trigger `quarantine`, masking the key with `***` in the payload, blocking the tool call via an agent-friendly error response containing `X-Loopers-Policy-Block: true`, updating persistent risk score by +30, and quarantining the agent key in Redis for a duration (default `1h`).

**Persistent Agent Identity & Behavioral Risk (Capability 3):**
Loopers tracks cross-session agent behavioral memory keyed by `loopers:risk_profile:{keyHash}` in Redis:
- Deterministic risk scoring: `+10` (deny), `+25` (quarantine), `+15` (escalate), `+5` (taint flag), `+30` (secret exfiltration from inspector), `-5` (decay per 24h).
- Automated lockouts: score > 75 triggers 1-hour auto-quarantine, score > 90 triggers permanent block.
- OPA policies evaluate `input.agent_risk.risk_score`, `input.agent_risk.persistent_taint_flags`, etc. Built-in preset: `zero_trust`.

**Outbound Semantic DLP Gate (Capability 4):**
When `server.dlp.enabled` is set to true in `loopers.yaml`, Loopers scans outbound LLM completion text across both non-streaming JSON envelopes and live SSE streaming chunks:
- PII Signatures: RFC 5322 Emails (with allowlist filtering), Credit Cards (Visa, MC, Amex, Discover with Luhn validation), US SSNs, and E.164 phone numbers.
- Internal Infrastructure: RFC 1918 private IPs (`10.x`, `172.16-31.x`, `192.168.x`), loopback, and internal host suffixes (`.internal`, `.local`, `.corp`).
- Action Planes:
  - `mask`: Rewrites sensitive tokens to `***` in-place inside provider completion JSON (OpenAI, Anthropic, Gemini, OpenRouter), recalculates `Content-Length`, and sets `X-Loopers-DLP-Redacted: true`.
  - `quarantine`: Severs completion connection with HTTP 403 or error SSE frame, sets `X-Loopers-DLP-Block: true`, sets 1-hour Redis lockout (`loopers:quarantine:{keyHash}`), increments persistent risk score (+30), and rejects subsequent calls at gateway auth layer.
  - Streaming SSE Sliding Window: 256-character rolling text window catches secret patterns split across chunk boundaries.

**Multi-Turn Conversation Drift Detection (Capability 5):**
When `session.drift_detection.enabled` is active, Loopers defends against multi-turn goal hijacking and gradual crescent context divergence across conversational dialogues:
- Persists initial turn ($T_1$) as the immutable session anchor in Redis (`loopers:session:{keyHash}:{sessionID}:anchor`).
- Evaluates token containment similarity ($75\%$ anchor grounding + $25\%$ immediate turn continuity) with trigram FNV-1a hashing and English stopword filtering.
- Maps drift attributes directly into OPA/Rego (`input.session.drift.drift_detected`, `input.session.drift.drift_score`) and YAML Policy Cards (`session.drift.drift_detected == true`). Built-in preset: `safety_drift`.

**Syntactic Normalization & Homoglyph Defense (Capability 6):**
Embedded Layer 3 pipeline (`internal/syntactic`) running 5-stage de-obfuscation on all inbound prompts and tool responses:
- TR39 Confusable Resolution: Cyrillic (`а`, `е`, `о`, `р`, `с`, `і`), Greek (`α`, `ο`, `ν`, `ρ`, `τ`), Mathematical Alphanumeric bold/italic (`𝐢𝐠𝐧𝐨𝐫𝐞`), Fullwidth (`ｉｇｎｏｒｅ`), and Enclosed runes (`ⓘⓖⓝⓞⓡⓔ`) normalized to canonical ASCII.
- Invisible Rune Stripping: Removes 28+ zero-width spaces (`\u200B`, `\u200C`, `\u200D`, `\uFEFF`), bidi directional overrides (`\u202E`, `\u200E`), soft hyphens, and variation selectors.
- Recursive Multi-Layer Decoding: Recursively unescapes double/triple URL percent-encoding (`%252e%252e` -> `..`), hex escapes (`\xHH`), unicode escapes (`\uHHHH`), and HTML entities (`&#105;`).
- Multi-Layer Payload Extraction: Unpacks Base64 printable text layers to inspect embedded instructions and secret tokens without corrupting binary data.
- Delimiter & Token Collapse: Unpacks padded token splitting (`i.g.n.o.r.e`) and leetspeak (`1gn0r3` -> `ignore`).
- Dual Policy Matching: Exposes `input.action.normalized_prompt` and `input.action.obfuscation.*` to OPA and automatically matches prompt conditions against both raw and normalized text.

---

## Getting Started & Core

- [Getting Started](/docs/getting-started): Step-by-step setup for both Docker (recommended) and Native Go installation. Covers creating a key, setting a budget, and routing your first request.
- [Architecture](/docs/architecture): How the Go reverse proxy, Redis atomic Lua scripts, and OPA engine interact. Read this to understand the request lifecycle.
- [What's New](/docs/whats-new): Latest features, changelog, and breaking changes.
- [FAQ](/docs/faq): Direct answers for common questions on loop detection, cost limits, MCP proxying, and key management.
- [Security](/docs/security): Responsible disclosure, security model, and threat mitigations.
- [Benchmarks](/docs/benchmarks): Throughput and latency benchmarks vs other proxies.

## Key Concepts

- [Budget Windows](/docs/concepts/budget-windows): How the five time windows (minute, hourly, daily, weekly, monthly) work independently. First limit hit blocks the request.
- [Session Budgets](/docs/concepts/session-budgets): Multi-turn agent cost tracking with per-session spend limits and `X-Loopers-Session-Id` header propagation.
- [Agent Loop Detection](/docs/concepts/agent-loop-detection): Fingerprint-based and velocity-based loop detection. Configurable thresholds in `loopers.yaml` under `loop_detection`.
- [Security Events](/docs/concepts/security-events): Structured JSON security event logging for policy blocks, budget exhaustion, and loop detection events.
- [Concurrency & Correctness](/docs/concepts/concurrency-correctness): How Redis Lua scripts prevent TOCTOU race conditions under high concurrency.

## Guides & Integrations

- [Agent CLI Integrations](/docs/guides/agent-cli-integrations): How to wrap `aider`, `openhands`, `pi`, `claude`, `codex`, `opencode`, and other CLI agents using `loopers exec`. Includes `LOOPERS_PROVIDER`, `--model-override`, and `--model-map` flag documentation with Windows, macOS, and Linux examples.
- [Trace Verification](/docs/guides/trace-verification): Offline compliance and regression auditing of AI agent execution traces using the loopers verify CLI.
- [Policy Engine (OPA/Rego)](/docs/guides/policy-engine): Complete OPA input schema, example Rego policies (allow by owner, deny by taint flag, restrict models by team), and agent-friendly error format for self-correction.
- [Framework Adapters](/docs/guides/framework-adapters): Native adapters for CrewAI and Microsoft AutoGen to route framework LLM traffic through Loopers.
- [MCP Setup](/docs/guides/mcp-setup): How to proxy MCP (Model Context Protocol) tool calls through Loopers for per-tool cost tracking and blast-radius prevention.
- [Monitoring with Grafana](/docs/guides/monitoring-grafana): Prometheus metrics endpoint (default: `127.0.0.1:9090`) and pre-built Grafana dashboard setup.
- [CI/CD Integration](/docs/guides/ci-cd-integration): Running Loopers in automated pipelines for budget-guarded test runs.
- [Kubernetes / Helm](/docs/guides/kubernetes-helm): Helm chart deployment for production Kubernetes clusters.

## SDKs

- [Python SDK](/docs/sdks/python): `loopers-client` package with LangChain (`ChatLoopers`) and LlamaIndex (`LoopersLLM`) adapters.
- [TypeScript SDK](/docs/sdks/typescript): `@loopers/sdk` for Node.js and Next.js, wraps the OpenAI client.

## Reference

- [CLI Reference](/docs/reference/cli): Full command reference for every `loopers` subcommand and flag.
- [Configuration (loopers.yaml)](/docs/reference/config): Complete config file reference — server, redis, proxy, policy, alerting, otel, loop_detection, session, mcp.
- [HTTP Headers Reference](/docs/reference/headers): All request and response headers used by Loopers (`X-Loopers-Provider-Key`, `X-Loopers-Session-Id`, `X-Loopers-Policy-Block`, etc).

## Complete Context File

- [llms-full.txt](/llms-full.txt): Single concatenated file containing all documentation above — use this when you need complete context about Loopers in one fetch.