A high-performance reverse proxy and AI gateway. One binary, one config file, low request overhead.
Website | Documentation | Quick Start | Examples | E2E Tests | Docs
Most teams run separate systems for HTTP proxying and AI traffic. SBproxy handles both in a single binary. One YAML config file covers your entire traffic layer: path-based routing, authentication, rate limiting, response caching, AI model routing with fallback chains, content safety guardrails, and more.
- Single binary with zero external dependencies. Works without Redis, a database, or a sidecar.
- Sub-millisecond overhead via compiled handler chains (no per-request config lookups).
- 200+ native LLM providers with OpenAI-compatible API. See docs/providers.md.
- Hot reload without restarts.
# Homebrew
brew tap soapbucket/sbproxy && brew install sbproxy
# Go
go install github.com/soapbucket/sbproxy/cmd/sbproxy@latest
# Docker
docker pull ghcr.io/soapbucket/sbproxy:latest
# Script
curl -fsSL https://download.sbproxy.dev | sh# sb.yml
proxy:
http_bind_port: 8080
origins:
"api.example.com":
action:
type: proxy
url: https://test.sbproxy.devsbproxy serve -f sb.yml
curl -H "Host: api.example.com" http://localhost:8080/echo# sb.yml
proxy:
http_bind_port: 8080
origins:
"ai.example.com":
action:
type: ai_proxy
providers:
- name: openai
api_key: ${OPENAI_API_KEY}
models: [gpt-4o, gpt-4o-mini]
default_model: gpt-4o-mini
routing:
strategy: fallback_chain
authentication:
type: api_key
api_keys: [my-key]
policies:
- type: rate_limiting
requests_per_minute: 60
algorithm: sliding_windowsbproxy serve -f sb.yml
curl -H "Host: ai.example.com" \
-H "X-API-Key: my-key" \
-H "Content-Type: application/json" \
http://localhost:8080/v1/chat/completions \
-d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Hello"}]}'Returns an OpenAI-compatible response regardless of which provider handled the request.
See examples/16-full-production.yml for a production-grade configuration combining API key auth, rate limiting, WAF, response caching, compression, CORS, security headers, path-based routing, and custom error pages.
All 16 examples in examples/ use test.sbproxy.dev as the backend and work out of the box.
| Feature | Description | Docs |
|---|---|---|
| Reverse Proxy | Forward requests to upstream servers with configurable timeouts | Config |
| Path-Based Routing | Route different paths to different backends via forward rules | Config |
| Load Balancing | 10 algorithms (round-robin, weighted, least-connections, IP hash, and more) with health checks | Config |
| AI Gateway | OpenAI-compatible API with 200+ native providers, model routing, fallback chains | AI Docs |
| WebSocket | Full-duplex WebSocket proxying | Config |
| gRPC | gRPC and gRPC-Web proxying | Config |
| GraphQL | GraphQL-aware proxying | Config |
| MCP Server | Model Context Protocol for AI agent tool use | Config |
| A2A Protocol | Google Agent-to-Agent protocol | Config |
| Feature | Description | Docs |
|---|---|---|
| Authentication | API keys, basic auth, bearer tokens, JWT (HS256/RS256/ES256), forward auth, digest | Auth Docs |
| WAF | OWASP Core Rule Set with paranoia levels 1-4, custom rules | Security |
| Rate Limiting | Sliding window, fixed window, token bucket, leaky bucket. Per-endpoint overrides. | Config |
| DDoS Protection | Adaptive rate-based detection with block, throttle, or challenge actions | Security |
| IP Filtering | Allowlist/blocklist with CIDR support and trusted proxy configuration | Security |
| CORS | Origin allowlist, method/header control, credentials, preflight caching | Config |
| Security Headers | HSTS, CSP, X-Frame-Options, Referrer-Policy, Permissions-Policy | Security |
| CSRF Protection | Token-based CSRF with cookie + header validation | Security |
| HTTP Signatures | RFC 9421 inbound verification and outbound signing | Security |
| Bot Detection | Per-origin bot detection with allow/deny lists | Security |
| CEL Expressions | Custom access control via Common Expression Language | Scripting |
| Feature | Description | Docs |
|---|---|---|
| Response Caching | TTL, stale-while-revalidate, stale-if-error, cache key customization | Config |
| Compression | gzip, brotli, zstd with content-type exclusions | Config |
| Request Modifiers | Header injection, URL rewrite, body replacement with template variables | Config |
| Response Modifiers | Response header injection, status override | Config |
| Transforms | JSON projection, HTML, Markdown, Lua JSON, template rendering, and 15+ more | Config |
| Error Pages | Custom error pages with Mustache template rendering | Config |
| Webhooks | Lifecycle callbacks (on_load, on_request, on_response) with sync and async modes | Webhooks |
| Session Management | Cookie-based sessions with configurable policies | Config |
| Feature Flags | Per-origin behavior overrides via headers or config | Config |
| Lua Scripting | JSON transforms and custom request/response logic | Scripting |
| Feature | Description | Docs |
|---|---|---|
| Structured Logging | Multi-backend (stderr, ClickHouse) with IP masking and sampling | Logging |
| Prometheus Metrics | Request latency, throughput, cache hit rates, error rates | Metrics |
| OpenTelemetry | Distributed tracing with OTLP export | Tracing |
| Events | Publish/subscribe event bus for lifecycle and security events | Events |
| PROXY Protocol | v1/v2 support for L4 load balancer deployments | Config |
| Protocol | Status |
|---|---|
| HTTP/1.1 | Supported |
| HTTP/2 | Supported (with connection coalescing) |
| HTTP/3 (QUIC) | Supported |
| WebSocket | Supported |
| gRPC | Supported |
| SSE | Supported (streaming) |
SBproxy compiles each origin config into an 18-layer handler chain at startup. Requests execute the pre-compiled chain as a function call sequence with zero map lookups or config re-reads.
Request -> Global Middleware (14 layers) -> Host Routing (O(1) lookup) -> Origin Chain (18 layers) -> Action
Origin handler chain (execution order):
AllowedMethods -> ForceSSL -> ErrorPages -> TrafficCapture ->
MessageSignatures -> Session -> ThreatProtection -> BotDetection ->
RateLimitHeaders -> Policies -> OnRequest -> Auth ->
RequestModifiers -> ResponseModifiers -> OnResponse ->
ResponseCache -> Transforms -> Action
See docs/architecture.md for the full startup flow, request flow, and package map.
cloud.sbproxy.dev provides enterprise features, managed hosting, and a configuration dashboard.
Enterprise capabilities include canary deployments, traffic shadowing, API versioning, geo-blocking, threat detection, AI guardrails, semantic caching, budget enforcement, WASM plugins, OAuth 2.0, A/B testing, orchestration pipelines, and more.
| Resource | Link |
|---|---|
| Full Documentation | sbproxy.dev/docs |
| Configuration Reference | sbproxy.dev/docs/config |
| AI Gateway Guide | sbproxy.dev/docs/ai |
| Security Guide | sbproxy.dev/docs/security |
| Scripting (CEL + Lua) | sbproxy.dev/docs/scripting |
| Architecture | docs/architecture.md |
| Examples | examples/ |
| Comparison | docs/comparison.md |
Contributions are welcome. Please open an issue to discuss your idea before submitting a pull request.
git clone https://github.com/soapbucket/sbproxy.git && cd sbproxy
go build ./... && go test ./...See CONTRIBUTING.md for details.
Apache License 2.0. See LICENSE for details.
SBproxy is a Soap Bucket LLC project.