Last modified: 2026-08-08
SBproxy is a high-performance reverse proxy and AI gateway built on Cloudflare's Pingora framework. It unifies traditional API proxying, AI model routing, Agent-to-Agent (A2A) communication, Model Context Protocol (MCP) tool integration, and Agent-specific workflows into a single binary.
This document breaks down SBproxy's capabilities into five core domains: API, AI, MCP, A2A, and Agent. For each area, you'll find a discussion of what the codebase does and links to the relevant deep-dive documentation and runnable examples.
At its core, SBproxy is an extremely capable reverse proxy with advanced traffic shaping and zero-downtime configuration reload: a candidate config is validated, constructed with rollback on failure, and committed atomically, while in-flight requests finish on the config snapshot they started with. Binary upgrades use rolling restarts; see Upgrade.
SBproxy routes traffic based on exact hostnames and dynamic forward rules. It supports complex deployment patterns like blue-green and canary rollouts.
- Docs: Configuration Schema, Routing & Fallback
- Examples: Basic Proxy, Forward Rules, Host Override, gRPC H2C, Error Pages, Headers & CORS, Compression
Traffic can be distributed across upstream targets using 8 algorithms (including round-robin, least connections, and ketama-style consistent hashing via ring_hash). Active health checks proactively remove failing targets from the pool.
- Docs: Performance & Load Balancing, Architecture
- Examples: Load Balancer, Active Health Checks, Circuit Breaker, LB Deployment
Protect your endpoints with 7 built-in authentication types: API Keys, Basic Auth, Bearer tokens, JWT (with JWKS), Forward Auth, Digest, and mTLS. You can also enforce fine-grained access control.
- Docs: OIDC Auth, Object Authz, Key Management, Web Bot Auth
- Examples: Auth JWT, Auth Forward, mTLS Client Auth, API Key, Basic Auth, Bearer Token, Bearer DPoP, CAP Auth, Inbound Keys, Sessions
A built-in Web Application Firewall (WAF) screens requests before they hit your upstream. It ships a curated, CRS-derived baseline of 16 rules: 4 built-in patterns plus a 12-rule managed bundle with CRS-style IDs and paranoia levels. The rule set extends through a signed remote rule feed, verified with HMAC-SHA256, cached on disk, and rejected when older than a configured staleness bound, and repeat offenders can be blocked persistently through strike-based blocking. Both corpora are independent flags and neither implies the other: owasp_crs.enabled: true gives you the 4 built-in patterns, and owasp_crs.managed_bundle: true adds the 12-rule bundle. Operators who need full OWASP CRS coverage (anomaly scoring, transformation pipelines, body processors) should put ModSecurity, Coraza, or a CDN WAF in front and keep SBproxy's WAF as a baseline layer. WAF options records why there is no SecLang engine in the dataplane, and gives the recipes for running one in front, publishing your own rules through the signed feed, and layering the policies already in the binary. SBproxy also mitigates DDoS attacks and HTTP request smuggling, and enforces token-bucket rate limiting.
- Docs: WAF Options, Threat Model, Exposed Credentials, Security Model Host
- Examples: WAF, Layered WAF, DDoS Protection, Rate Limiting, IP Filter, CSRF, Defense in Depth, DLP Catalog, HSTS, Page Shield, Security Headers, SRI, Request Limit
When declarative config isn't enough, inject custom logic via Lua, JavaScript, WebAssembly (WASM), or CEL expressions. You can rewrite headers, transform payloads, and implement bespoke policies. Package complex behaviors with Extension Bundles.
- Docs: Scripting Guide, Extension Bundles, Custom Engines, WASM Development
- Examples: CEL Policy, Transform Lua, WASM Transform, Javascript, JSON, JSON Projection, JSON Schema, Markdown, Payload Limit, Replace Strings, Template, Variables, Encoding, Storage Action
Dynamically emit OpenAPI specs for your routes, and validate incoming traffic against them. The Admin API allows real-time metric querying and configuration updates.
- Docs: Admin API Guide, OpenAPI Emission, OpenAPI Validation
- Examples: OpenAPI Emission, OpenAPI Validation
The ai_proxy action turns SBproxy into an OpenAI-compatible API gateway capable of routing requests to 72 native providers and over 200 models.
Send standard chat completion requests to the proxy, and it routes them based on the model name. You can configure multiple providers and utilize fallback chains to ensure high availability.
- Docs: AI Gateway, Providers List, Local Inference, Model Host
- Examples: AI Multi-Provider, AI OpenRouter, AI Local Serving, Bedrock Direct, Gemini Direct, Model Group, Streaming
Go beyond round-robin with LLM-aware routing strategies like lowest latency, least token usage, cost-optimized, cascade, or outcome-aware routing. The gateway categorizes upstream failures and retries intelligently.
- Docs: AI LLM Aware Resilience, AI Outcome Aware Routing, AI Load Balancer Benchmark
- Examples: AI Cascade Routing, AI Outcome Aware Routing, AI Resilience, Cost Optimized, Routing Fallback
Enforce hard or soft budgets on AI spend by workspace, user, or key. Soft-landing budgets step through fixed warn and downgrade thresholds of the current spend window before the cap blocks; the mechanism is a threshold ladder, not a spend forecaster. SBproxy calculates token counts and USD costs locally, emitting metrics for attribution and saving tamper-evident logs.
- Docs: AI Budget Soft-Landing, AI Usage Ledger, Value Ledger Economics, Metering
- Examples: AI Budget, AI Usage Ledger, Metering Verify, Model Rate Limits, Surface Rate Limits, Waste Signals, Attribution Tags
Apply input/output guardrails using local classifiers or external APIs to detect toxicity, jailbreaks, and PII. You can use the Guardrail Mesh to fuse multiple safety verdicts and write complex rules with the AI CEL policy plane.
- Docs: Guardrails, AI Guardrail Mesh, AI Policy CEL, Prompt Injection, Classifier Sidecar
- Examples: AI Guardrails, AI Safety Classifiers, AI Regex DLP
Reduce token costs and latency by stripping redundant context from prompts or using semantic caching to serve identical queries directly from the proxy edge.
- Docs: AI Context Compression, Cache Reserve
- Examples: AI Context Compression Redis, Semantic Cache Local, Response Caching, Context Compression Mesh, Origin Keys Cache
SBproxy acts as an MCP gateway, allowing AI models and agents to securely discover and execute tools within your infrastructure.
Federate multiple MCP servers behind a single SBproxy endpoint. Agents can seamlessly discover capabilities across your microservices while SBproxy handles authentication and routing.
- Docs: MCP Overview, Use Case: MCP Federation
- Examples: MCP Federation, MCP Code Mode
Restrict which agents can call which tools. SBproxy's MCP implementation includes robust Role-Based Access Control (RBAC), quotas, and guardrails specifically designed for tool execution.
- Docs: Migration: MCP RBAC, MCP Gateway Guardrails
- Examples: MCP RBAC Quotas
Manage the lifecycle of your MCP tools with progressive discovery and strict tool versioning, ensuring that agents always interact with compatible tool schemas.
- Docs: Tool Versioning
- Examples: MCP Tool Versioning, MCP Tool Rollout, MCP Progressive Discovery
As multi-agent systems grow, SBproxy facilitates the complex web of communication between autonomous agents.
SBproxy provides a dedicated gateway layer for Agent-to-Agent interactions. It normalizes protocols, handles identity verification between agents, and ensures that asynchronous messages and capability handoffs occur reliably.
- Docs: A2A Gateway
- Examples: A2A Protocol, A2A Prompt Injection
Beyond standard API and AI proxying, SBproxy ships with features tailored explicitly for the needs of autonomous agents navigating the web and consuming APIs.
Provision unique identities for your agents and equip them with specific skills. SBproxy tracks agent behavior and authorizes actions based on their assigned identities.
- Docs: Getting Started: Agent Identity, Agent Skills
- Examples: Agent Skills
Agents can operate autonomously, which means they can rack up costs or aggressively scrape resources. Enforce strict agent-specific budgets and utilize crawl control mechanisms to throttle autonomous scraping behavior.
- Docs: Agent Budget, AI Crawl Control, Use Case: Meter Crawlers
- Examples: Agent Budget, AI Crawl Control
Serve content formatted specifically for LLM consumption. SBproxy can dynamically strip heavy HTML, inject markdown, or serve llms.txt files to optimize the context window for visiting agents.
- Docs: Content for Agents
- Examples: Markdown for Agents, Transform HTML to Markdown, Robots LLMs txt