Proxy Mode

bserver can act as a reverse proxy for any virtual host. Instead of serving files from disk, all requests to the vhost are forwarded to a backend HTTP server and the responses are relayed back to the client.

Setup

Create a vhost directory containing a single index.yaml with an http: key pointing to the backend address:

www/example.com/index.yaml

http: '192.168.1.2:8080'

That's it. All requests to example.com will be proxied to http://192.168.1.2:8080.

How It Works

When a request arrives, bserver checks the vhost's index.yaml before doing any file serving. If the file contains an http: key, a reverse proxy is created for that backend and the request is forwarded.

• The proxy is created once and cached. Subsequent requests reuse it.
• If you edit index.yaml, the change is picked up automatically on the next request (mtime-based cache invalidation).
• If the backend is unreachable, the client receives a 502 Bad Gateway response and the error is logged.

Backend Address Format

The http: value can be specified with or without a scheme:

Value	Proxies to
192.168.1.2:8080	http://192.168.1.2:8080
http://192.168.1.2:8080	http://192.168.1.2:8080
http://localhost:3000	http://localhost:3000
http://10.0.0.5:9090/app	http://10.0.0.5:9090/app

If no scheme is provided, http:// is assumed.

Examples

Proxy to a local application

Run a Node.js app on port 3000 and expose it as myapp.example.com:

mkdir -p www/myapp.example.com

# www/myapp.example.com/index.yaml
http: 'localhost:3000'

Proxy to a backend server on the network

Forward internal.example.com to a machine on the LAN:

mkdir -p www/internal.example.com

# www/internal.example.com/index.yaml
http: '192.168.1.50:8080'

Proxy with a path prefix

Forward to a backend that serves from a subpath:

# www/api.example.com/index.yaml
http: 'http://10.0.0.5:9090/v2'

SSRF Protection

A vhost index.yaml is a file on disk — but an attacker who can write to it could otherwise turn bserver into an SSRF gateway. bserver refuses to proxy to:

• Loopback addresses (127.0.0.0/8, ::1)
• Link-local addresses (169.254.0.0/16, including AWS metadata 169.254.169.254)
• Private network ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
• Unspecified addresses (0.0.0.0, ::)
• Multicast addresses

If you legitimately need to proxy to a private backend (the common case on a LAN), opt in with allow-private: true:

# www/internal.example.com/index.yaml
http: '192.168.1.50:8080'
allow-private: true

API Key Protection

Add an api-key to require Bearer-token authorization on every request to a proxied vhost:

# www/api.example.com/index.yaml
http: 'localhost:9090'
api-key: 'sk-secret-string-here'

Clients must send Authorization: Bearer sk-secret-string-here or the server returns 401 Unauthorized. The header is then stripped before the request is forwarded, so the backend never sees the bserver key.

This pairs well with rate limiting (10 wrong attempts blocks the IP).

What Gets Proxied

When a vhost is in proxy mode, all requests to that domain are forwarded to the backend. This includes:

• All URL paths
• Query strings
• Request headers
• Request bodies (POST, PUT, etc.)

The following bserver features are still applied to proxied requests:

• Access logging — proxied requests appear in the log like any other
• Security headers — X-Content-Type-Options, X-Frame-Options, and Referrer-Policy are added to responses
• Rate limiting — error responses from the backend count toward the rate limiter
• TLS termination — HTTPS is handled by bserver; the backend connection uses plain HTTP

Switching Between Proxy and Normal Mode

To switch a vhost from proxy mode to normal file serving, simply remove or rename the http: key in index.yaml (or replace it with a main: definition). The change takes effect on the next request.

To switch from normal mode to proxy mode, add an http: key to index.yaml. Any other keys in the file are ignored when http: is present.

Logging

When a proxy vhost is first detected (or its configuration changes), bserver logs the mapping:

Proxy vhost /path/to/www/example.com -> http://192.168.1.2:8080

Backend errors are logged with the domain and target:

proxy error for example.com -> http://192.168.1.2:8080: dial tcp 192.168.1.2:8080: connect: connection refused