Architecture

What SBproxy is and how requests flow through it

What is SBproxy

SBproxy is a reverse proxy and AI gateway in a single binary. It sits between your clients and backend services, routing traffic by hostname. Each hostname maps to an origin configuration that defines what happens to the request: where it goes, what security applies, how the response is transformed, and whether it gets cached.

The Config Model

All configuration lives in a YAML file called sb.yml. It has two top-level keys: proxy for server settings and origins for hostname-to-backend mappings.

A minimal config needs just a hostname and an action:

proxy:
  http_bind_port: 8080

origins:
  "api.example.com":
    action:
      type: proxy
      url: https://backend.example.com

A fully-loaded config adds security, caching, modifiers, and more. These are all siblings of action, never nested inside it:

origins:
  "api.example.com":
    action:
      type: proxy
      url: https://backend.example.com
    authentication:
      type: jwt
      jwks_url: https://auth.example.com/.well-known/jwks.json
    policies:
      - type: rate_limiting
        requests_per_second: 100
        burst: 200
        key: ip
      - type: waf
        owasp_crs:
          enabled: true
    request_modifiers:
      - headers:
          set:
            X-Request-ID: "{{request.id}}"
    response_cache:
      enabled: true
      ttl: 5m

See the Configuration Guide for a full breakdown of every component.

Request Lifecycle

When a request arrives, it passes through nine stages in order. Each stage is controlled by a specific part of the origin configuration.

1. TLS Termination

SBproxy handles TLS automatically. Clients connect over HTTPS, and the proxy terminates the connection before processing begins. Certificates are managed with automatic renewal.

2. Host Pre-filtering

The proxy checks the request's Host header against a bloom filter of known hostnames. Unknown hostnames are rejected immediately without loading any configuration. This protects against scanning and reduces unnecessary work.

3. Origin Resolution

The hostname is matched to an origin configuration. The proxy first tries an exact match (e.g., api.example.com). If no exact match is found, it tries a single-level wildcard (e.g., *.example.com). Wildcard origins match any subdomain at one level, so *.example.com matches api.example.com but not deep.sub.example.com.

4. Request Rules and Forwarding Rules

request_rules determine whether this origin handles the request at all, based on path, method, headers, or expressions. forward_rules can redirect the request to a different origin configuration based on matching criteria. Each forwarding rule can embed an inline origin with its own action, auth, and policies.

5. Policy Enforcement

Policies execute before authentication, in the order they appear in the configuration array. This includes WAF rules, DDoS protection, rate limiting, IP filtering, security headers, and CSRF protection. If any policy blocks the request, processing stops immediately.

6. Authentication

If the origin has an authentication block, the request is authenticated. SBproxy supports API key, basic auth, bearer token, JWT (with JWKS auto-discovery), forward auth, digest, and Web Bot Auth (RFC 9421 HTTP Message Signatures for AI agents). Authenticated claims are available as template variables ({{auth.data.*}}) for use in later stages.

7. Cache Check

If response_cache is configured and the request matches the cache conditions (method, path, headers), the proxy returns the cached response immediately. Cache hits skip action execution entirely. Stale-while-revalidate can serve stale content while refreshing in the background.

8. Action Execution

The action block determines what happens to the request. This is where the proxy forwards to a backend (proxy), routes across multiple backends (load_balancer), returns a static response (static), redirects (redirect), proxies AI traffic (ai_proxy), serves MCP tools (mcp), or executes any of the other built-in action types.

9. Response Processing

After the action returns a response, transforms modify the response content (JSON projection, HTML injection, Lua transformations). Then response_modifiers adjust headers, status codes, and body. Finally, if caching is enabled, the response is stored for future requests.

Where AI Fits

The ai_proxy action type plugs into the same lifecycle at stage 8. Everything before it - policies, authentication, caching - applies to AI traffic the same way it applies to any other traffic. Inside the action, the AI gateway handles provider selection, format translation (all providers use the OpenAI-compatible API), streaming, failover, and cost tracking. See the AI Proxy docs for details.

Configuration Loading

SBproxy loads configuration from a YAML file on disk. When the file changes, the proxy reloads automatically with zero downtime - no restart required. The configuration file is plain text and works with any version control system.

Hostnames can use wildcards (*.example.com) to handle any subdomain with a single origin configuration.

Next Steps

← PreviousExamplesNext →CLI Reference