sbproxy

Last modified: 2026-09-09

sbproxy is a single Rust binary that puts one policy engine in front of three kinds of traffic: HTTP APIs, AI model calls across 70 native providers reaching 200+ models through one OpenAI-compatible endpoint, and MCP or agent-to-agent tool calls. All three run through the same request pipeline, so a rate limit, a guardrail, a budget cap, and an audit record behave the same way no matter which traffic type triggered them. Every feature in this repository ships under Apache-2.0.

Why sbproxy

• Extension without a sidecar. Five engines run in the same process as the request pipeline: CEL for one-line gates, Rego via the Regorus interpreter for teams migrating policies they already wrote for OPA, Lua and JavaScript for stateful transforms, and sandboxed WebAssembly for anything those can't express. There is no OPA server to run alongside the proxy and no separate plugin daemon. Extension bundles add a hook (action, auth, policy, or transform) from a local directory or a git checkout pinned to a commit SHA plus a content digest (the entry file by default, the whole bundle on request), with optional signature verification, hot-reloaded with no rebuild. See Extending sbproxy.

• A tamper-evident audit trail. Security, config, key-mutation, and admin-action events each append to their own hash-chained, Ed25519-signed log when you opt the channel in; sbproxy audit verify re-derives the chain from genesis and catches a tampered entry. Guardrail and policy decisions publish separately as typed records to your SIEM. See Audit log.

• Coverage graded against OWASP's LLM Top 10. AI gateway security coverage rates every OWASP LLM Top 10 (2026) category enforced, enforced with named limits, or out of gateway scope, plus eight gateway-layer risks that list doesn't cover. Budgets deny at the cap across seven scopes instead of logging past it, and every outbound destination is tracked across fourteen traffic purposes behind a default-deny allowlist; engine artifact downloads are the one purpose it still can't reach.

• An MCP gateway built for an upstream you don't control. Tool contracts are pinned by digest in a committed lockfile and re-checked on every catalog refresh; a definition that moved is graded by a compatibility oracle and either reported or blocked, a rename is caught by re-digesting the old name, and a version bump that understates a breaking change fails a linter check before it ships. Tool access is scoped per caller, default-deny. See MCP and agents.

• Serve models locally, on the same binary. sbproxy run starts a managed local model and hands it the same keys, budgets, and usage ledger that govern requests routed to a hosted provider. A semantic cache serves near-duplicate prompts from an embedding index; run it fully local with the sidecar or in-process source. Metered requests cut Ed25519-signed, hash-chained receipts a buyer can re-derive and verify without trusting your dashboard. See Run your first managed model, Self-hosting, and Attested metering.

Start here

Install a release on Linux or Apple Silicon macOS:

curl -fsSL https://download.sbproxy.dev | sh
export PATH="$HOME/.local/bin:$PATH"
sbproxy --version

The installer writes to ~/.local/bin by default. Keep the export in your shell profile if that directory was not already on PATH. Linux amd64, Linux arm64, and Apple Silicon macOS arm64 have release archives. Intel Macs can use the Linux image in Docker or build from source. See the runtime manual for the complete install matrix and checksums.

Run the credential-free gateway example next. It starts a local upstream, puts an API behind the gateway, adds an MCP tool, then sends a local OpenAI-compatible completion through the same listener.

git clone https://github.com/soapbucket/sbproxy
cd sbproxy
for config in upstream.yml api.yml mcp.yml sb.yml; do
  sbproxy validate "examples/enterprise-ai-gateway/$config"
done

Follow the getting-started guide.

Choose your job

If you need to	Start with
Understand the parts of a gateway	Core concepts
Trace a request stage by stage, hook by hook	Request flow
Put an existing HTTP API behind policy	API gateway guide
Run a local model	Run your first managed model
Route to hosted models	AI gateway reference
Expose or federate MCP tools	MCP and agents
Add policy or transform logic without a rebuild	Extending sbproxy
Prove what the gateway enforces	Security
Run the Kubernetes operator	Operator quickstart
Upgrade a running deployment	Upgrade guide

Install alternatives

Homebrew:

brew install soapbucket/tap/sbproxy

Docker. The published image has no default configuration command, so mount the file and name the command:

docker pull soapbucket/sbproxy:latest
docker run --rm -p 8080:8080 \
  -v "$PWD/sb.yml:/etc/sbproxy/sb.yml:ro" \
  soapbucket/sbproxy:latest serve -f /etc/sbproxy/sb.yml

Build from source when you need a local development binary:

make build-release
target/release/sbproxy --version

Documentation and examples

Documentation index groups the guides by first run, traffic type, operations, and reference material. The examples/ directory contains complete configurations. For the configuration schema, use configuration.md; for the command surface, use manual.md.

Related projects

• Homebrew tap: Homebrew packaging for sbproxy.
• Agentic security demo: a Docker Compose walkthrough of agent detection, signed requests, and agent budgets.
• sbproxy-bench: a shared benchmark harness for comparing HTTP proxies and AI gateways.
• ADRF specification: the YAML format and schema for agent-detection rule packs.
• Pingora fork: Soap Bucket's fork of Cloudflare's proxy framework, used by sbproxy.

Contributing and license

See CONTRIBUTING.md for the contributor workflow. sbproxy is released under Apache License 2.0. See NOTICE and TRADEMARKS.