caddy_reverse_proxy
Define reverse proxy routing by setting incoming domain and upstream targets. Provide a stable id to update the route in place, preventing duplicate entries.
Instructions
Add a reverse proxy route. The most common operation — just specify where traffic comes from and where it goes. Example: from='api.local' to=['localhost:3000']. When id is OMITTED the route is appended to the server's routes array — calling the tool twice with the same args produces TWO duplicate routes (non-idempotent). When id is SUPPLIED the route is written via PATCH under that @id, so repeat calls REPLACE in place (idempotent). Strongly recommended: supply a stable id for any route managed from automation or production tooling. Note: @ids are config-global in Caddy (NOT route-scoped). If id collides with an @id used by a non-route object (TLS issuer, server, etc.) the call refuses with an error rather than clobbering it. Once an @id is registered to a route under one server, subsequent calls update that route in place regardless of the server argument. Upstream scheme is honored: an https:// upstream gets a TLS transport and defaults to port 443, anything else is dialed in the clear. A to list that MIXES https:// and non-https entries is refused — the TLS transport applies to the whole handler, not per-upstream — so split those into two routes or use caddy_add_route.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Optional stable @id for the route. When set, repeat calls REPLACE the route in place (idempotent). When omitted, the route is APPENDED — calling twice with identical args creates a duplicate route. @ids are config-global in Caddy: if this id is already used by a non-route object the call refuses rather than clobbering it. | |
| to | Yes | Upstream addresses, at least one (e.g., ['localhost:3000', 'localhost:3001']). An 'https://' prefix dials the upstream over TLS (port 443 unless one is given); http:// and bare addresses are dialed in the clear. Do not mix https:// and non-https entries in one call. | |
| from | Yes | Domain, path, or domain/path to match (e.g., 'api.local', '/api/*', 'app.local/ws') | |
| server | No | Caddy server name (default: srv0) | srv0 |