BareProxy.com

Introducing BareProxy, the Reverse Proxy That Explains Itself

Thu, 01 Oct 2026 00:00:00 +0000

Most applications use a small part of nginx. They terminate TLS, route by host and path, spread requests over backends that are up, change config without dropping traffic, and sometimes need to know what happened to one request. BareProxy is a reverse proxy for that part, with a core small enough to read in an afternoon.

The whole config for a site with an API, a web front end and a www redirect is 21 lines. A newcomer can read it in five minutes, and nothing in it depends on a precedence order: rules are tried from the top, and the first match wins.

How BareProxy Plan Shows What a Config Change Will Do Before It Goes Live

Wed, 30 Sep 2026 00:00:00 +0000

The riskiest moment in a proxy’s day is a config change. Cloudflare’s two outages at the end of 2025 both started with one that reached every server within seconds. BareProxy checks every config in full before it can go live, and plan goes one step further: it says which requests will be handled differently.

That works because BareProxy has no regular expressions and no scripting. Every matcher is an exact value, a prefix or a set, so the requests a site can receive fall into a finite number of classes, and every request in a class is handled the same way. plan works out what happens to each class under the old config and the new one, and prints the classes that change.

One Record per Request: How BareProxy Tracing Works

Tue, 29 Sep 2026 00:00:00 +0000

Every request BareProxy handles gets a random ID, sent to the backend and back to the client in a BareProxy-Id header, and shown on every error page BareProxy writes. When someone reports a problem, they can quote it.

Every request also leaves exactly one record: one JSON line with the rule that matched, the config version that handled it, every backend tried or passed over and why, and the timings. Records go to the trace log and stay in memory for quick lookups.

BareProxy Modules: Nine Add-Ons Around a Bare Core

Mon, 28 Sep 2026 00:00:00 +0000

BareProxy Core does six things: proxying, TLS, routing, backend health, config changes and request tracing. Everything else is a module, compiled in only when you want it. A Bare build carries the core alone. A Full build carries every module.

There are nine: Static, Compress, Cache, Limit, Auth, Split, Guard, Export and Fleet. Each plugs in at a fixed point in the request, before routing, as a rule’s action, around the backend call, on the response, on the record or on config changes.

Why BareProxy Routes on the Same Path It Forwards

Sun, 27 Sep 2026 00:00:00 +0000

Many proxy bypasses share one cause: the proxy reads a path one way and the application reads it another. A rule that blocks /admin/ does nothing if the request arrives as /api/%2e%2e/admin and the application decodes it after the proxy has let it through.

BareProxy normalizes every path once. It decodes escapes of plain characters, resolves . and .. segments, and merges runs of slashes. Then it routes on that form and sends the backend exactly the same form. Encoded slashes and backslashes are refused unless a site opts in.

About

Mon, 01 Jan 0001 00:00:00 +0000

BareProxy is a project at an early stage. It asks how little machinery it takes to provide the part of nginx that most applications use, and answers with a bare core and a set of add-on modules around it. Version 0.1 is an Alpha. This site shows where the project stands.

Why the Project Exists

Most applications use a small part of nginx. They need TLS, routing by host name and path, requests spread over backends that are actually up, config changes that don’t drop traffic, and a way to find out what happened to a request when something breaks. The proxies that do this well carry decades of features most sites never touch. Each of those features is code that runs at the edge, in front of everything else.

Config Reference

Mon, 01 Jan 0001 00:00:00 +0000

A BareProxy config is one file. A line in the first column opens a block (global, site or pool), and the indented lines under it belong to it. Blocks don’t nest, and the whole grammar fits on one page.

This is a complete config for a site with an API, a web front end and a www redirect:

# /etc/bareproxy/bareproxy.conf
global
  acme-email ops@example.com

site example.com
  route /healthz -> respond 200 "ok"
  route /api/* -> api strip
  route /* -> web

site www.example.com
  route /* -> redirect 301 https://example.com

pool api
  backend 10.0.0.11:8080
  backend 10.0.0.12:8080
  backend 10.0.0.13:8080
  health /healthz

pool web
  backend 10.0.0.21:3000
  backend 10.0.0.22:3000

What It Does

site example.com serves HTTPS on port 443 with a certificate from Let’s Encrypt, and redirects plain http:// requests to https://.
/healthz is answered by BareProxy itself, so a monitor can check the proxy without touching the application.
Everything under /api/ goes to pool api with the prefix stripped: /api/orders reaches the backend as /orders.
www.example.com redirects to a bare origin, so the path and query are kept.
Pool api checks each backend with GET /healthz every 5 seconds. Pool web has no checks, so failed connections on live traffic take its backends out.

Rules

route [METHODS] PATH [header NAME[=VALUE]]... -> ACTION

Contact

Mon, 01 Jan 0001 00:00:00 +0000

The project would like to hear from:

Teams running nginx who would like to try a smaller proxy on their own traffic.
Engineers with a config, a traffic pattern or a failure the project should test against.
Anyone with a question about the core, the modules or the figures on this site.

Write to info@bareproxy.com.

If you are writing about your own setup, it helps to mention what you run today, roughly how many sites and backends sit behind it, and which nginx features you actually use.

Demo

Mon, 01 Jan 0001 00:00:00 +0000

BareProxy’s own commands, run against the config on the config reference page. Each one reads the same compiled config the proxy routes with, so what it prints is what the proxy does.

Explain a Request Before It Arrives

explain walks the rules from the top, says why each one did or didn’t match, and shows which backend would get the request right now.

$ bareproxy explain GET https://example.com/api/orders
Running config, version 12
Site example.com (line 5): exact host match
  line 6   route /healthz -> respond 200 "ok"   no: path is not /healthz
  line 7   route /api/* -> api strip            match
Sent upstream as GET /orders with Host: example.com
Pool api (line 13): 2 of 3 up, fewest in flight wins
  10.0.0.11:8080   up, 0 in flight              next pick
  10.0.0.12:8080   up, 2 in flight
  10.0.0.13:8080   down since 14:02:10, 3 failed checks

Ask What Happened to a Request

Every response carries a BareProxy-Id header, and every error page shows it. Give any unique part of it to why:

Modules

Mon, 01 Jan 0001 00:00:00 +0000

Everything outside the core is a module. Modules are compiled in when BareProxy is built, so a binary without a module carries none of its code. Official builds come in two forms: Bare, the core alone, and Full, the core with every module. bareproxy modules lists what a binary contains.

The Nine Modules

Module	What it adds	Where it plugs in
BareProxy Static	Files and single-page apps served from a folder, with index files and a fallback to `index.html`	A rule’s action
BareProxy Compress	gzip and zstd compression, chosen by what the client accepts	The response
BareProxy Cache	Responses that say they can be cached, kept in memory or on disk, with purge by path prefix	Around the backend call
BareProxy Limit	Request and connection limits per client address, per rule or per site	Before routing
BareProxy Auth	API keys, basic auth, or the check handed to an identity service	Before routing
BareProxy Split	Weighted and canary splits between pools, by percentage or by header	A rule’s action
BareProxy Guard	Watches proxy errors after an apply, and rolls the change back by itself if they jump	Config changes
BareProxy Export	Request records sent to OpenTelemetry and log stores	The record
BareProxy Fleet	One plan applied across many instances, with shared history and request search	Config changes and records

Rules Every Module Follows

The core never depends on a module. Take any module out and the core still builds and passes all of its tests.
Fixed plug-in points. A module hooks in before routing, as a rule’s action, around the backend call, on the response, on the record or on config changes. It can’t change how the core matches requests.
The core’s promises still hold. A module’s config lines are checked before they go live. explain shows what the module did to a request, plan reports what a change to its settings affects, and every request it touches still leaves exactly one record.
A budget of its own. Each module stays under 1,500 lines of Go and goes through the same tests as the core.

What Modules Look Like in a Config

Each module adds a few lines of its own. Here Limit and Compress apply to the whole site, Static and Split are rule actions, and Cache sits on a pool:

Roadmap

Mon, 01 Jan 0001 00:00:00 +0000

BareProxy goes from a bare core to a platform one step at a time. Each step ships when its tests pass and its numbers are measured.

Stage	What it brings	Status
0.1 Alpha	BareProxy Core and nine add-on modules; `explain`, `plan` and `why`	Now
0.2 Beta	Pilots on real traffic; speed and memory measured against nginx with the same routes	Next
0.3	HTTP/2 to backends, and with it gRPC; the PROXY protocol from load balancers in front	Planned
0.4	BareProxy Fleet for many instances; Guard switched on by default	Planned
1.0	License chosen and first public release	Planned

What Stays Fixed

Every stage keeps the core’s rules. The core stays under its 5,000-line budget, matchers stay exact values, prefixes or sets, and a bad config never replaces a good one. New features arrive as modules unless every site needs them.

The Platform

Mon, 01 Jan 0001 00:00:00 +0000

BareProxy is a bare core with add-on modules around it. The core does six things and stops there. Modules add the rest, one at a time, and the core needs none of them.

BareProxy Core

What it does	How
Reverse proxy	HTTP/1.1 and HTTP/2 from clients, HTTP/1.1 to backends. WebSocket and streamed responses pass straight through.
TLS	Certificates from Let’s Encrypt or any ACME CA, obtained and renewed on their own, or loaded from files. TLS 1.2 minimum.
Routing	By host name, exact path or path prefix, method and header. The first matching rule wins.
Backend health	Active checks plus failure counting on live traffic. Requests go to the healthy backend with the fewest requests in flight.
Config changes	A new config is checked in full, then swapped in at once. Requests in flight finish on the old one, removed backends drain, and one command rolls back.
Request tracing	Every request gets an ID and leaves one record. `why`, `tail`, `explain` and `plan` read them.

Design Rules

Match on what you forward. The path is normalized once, routed on, and sent to the backend in that same form.
First match wins. Rules are read from the top. There is no precedence order to learn.
Matchers are exact values, prefixes or sets. No regular expressions, no variables, no scripting. That is what lets plan say exactly which requests a change affects.
A bad config never replaces a good one. Every config is checked in full on apply, on reload and at startup.
One record per request, and any record can be explained.
Nothing from outside the Go project. Go’s standard library and the Go team’s own packages, and nothing else.

How a Request Is Handled

The connection arrives, and the TLS handshake picks the certificate and HTTP/1.1 or HTTP/2.
BareProxy gives the request an ID, checks it and normalizes its path.
The host picks the site, and the site’s rules are tried from the top.
The rule answers directly, redirects, or names a pool.
The pool picks the backend with the fewest requests in flight, and BareProxy forwards a fresh request to it, with one retry if the connection can’t be opened.
The response streams back, and the request’s record is written.

The config behind all this fits on one page. The config reference has a complete example, and the modules page shows where each add-on plugs in.