User Guide


proxy facilitates both a basic reverse proxy and a robust load balancer. The proxy has support for multiple backends and adding custom headers. The load balancing features include multiple policies, health checks, and failovers. Caddy can also proxy WebSocket connections.

This middleware adds a placeholder that can be used in log formats: {upstream} - the name of the upstream host to which the request was proxied.


In its most basic form, a simple reverse proxy uses this syntax:

proxy from to

However, advanced features including load balancing can be utilized with an expanded syntax:

proxy from to... { policy name [value] fail_timeout duration max_fails integer max_conns integer try_duration duration try_interval duration health_check path health_check_port port health_check_interval interval_duration health_check_timeout timeout_duration header_upstream name value header_downstream name value keepalive number timeout duration without prefix except ignored_paths... upstream to insecure_skip_verify preset }

Note that in order to do proper, redundant load balancing in the event of failures, you must set fail_timeout and try_duration to values > 0.

Everything after the first to is optional, including the block of properties enclosed by curly braces.


The following presets are available:


There are several load balancing policies available:


Proxy all requests within /api to a backend system:

proxy /api localhost:9005

Load-balance all requests between three backends (using random policy):

proxy / web1.local:80 web2.local:90 web3.local:100

Same as above, with header affinity:

proxy / web1.local:80 web2.local:90 web3.local:100 { policy header X-My-Header }

Round-robin style:

proxy / web1.local:80 web2.local:90 web3.local:100 { policy round_robin }

With health checks and proxy headers to pass hostname, IP, and scheme upstream:

proxy / web1.local:80 web2.local:90 web3.local:100 { policy round_robin health_check /health transparent }

Proxy WebSocket connections:

proxy /stream localhost:8080 { websocket }

Proxy everything except requests to /static or /robots.txt:

proxy / backend:1234 { except /static /robots.txt }

Proxy to a backend with HTTPS on the standard HTTPS port:

proxy / https://backend