Quick Start

Get up and running with SBproxy in minutes

Welcome to SBproxy

SBproxy is a high-performance reverse proxy and AI gateway in a single binary. Install it, create a config file, and start routing traffic in under a minute.

Step 1: Install

curl -fsSL https://download.sbproxy.dev | sh

Or with Homebrew:

brew install soapbucket/tap/sbproxy

Or with Docker:

docker pull soapbucket/sbproxy:latest

If what you came for is a local model, the install is already the hard half. One more command picks an engine for your hardware, fetches and verifies the weights, and prints an OpenAI-compatible endpoint. The same command works on a Linux GPU box, a Mac, or plain CPU:

sbproxy run qwen2.5-0.5b-instruct --variant q4_k_m

See Run your first model in 60 seconds for the full walkthrough, and the self-hosting guide for local models behind gateway policy with hosted fallback.

Step 2: Create Your First Config

Create a file called sb.yml with a simple reverse proxy origin:

proxy:
  http_bind_port: 8080

origins:
  "api.example.com":
    action:
      type: proxy
      url: https://test.sbproxy.dev

Step 3: Start the Proxy

sbproxy serve -f sb.yml

Test it:

curl -H "Host: api.example.com" http://localhost:8080/

Step 4: Route AI Traffic (Optional)

Set up a multi-provider AI gateway by adding an origin with the ai_proxy action:

proxy:
  http_bind_port: 8080

origins:
  "ai.example.com":
    action:
      type: ai_proxy
      providers:
        - name: openai
          api_key: sk-your-openai-api-key
          models: [gpt-4o-mini]
      default_model: gpt-4o-mini

Replace sk-your-openai-api-key with your actual key. For production, use secrets management to keep keys out of config files. Start the proxy:

sbproxy serve -f sb.yml

Send a request:

curl -H "Host: ai.example.com" http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hello"}]}'

Step 5: Add Security

Add authentication to protect your origin. Authentication is a sibling of action, not inside it:

proxy:
  http_bind_port: 8080

origins:
  "api.example.com":
    action:
      type: proxy
      url: https://test.sbproxy.dev
    authentication:
      type: api_key
      api_keys:
        - my-secret-key
    policies:
      - type: rate_limiting
        requests_per_second: 100

Test it:

curl -H "Host: api.example.com" -H "X-API-Key: my-secret-key" http://localhost:8080/

Next Steps

Next →Run your first model in 60 seconds