Configuration

Headers

Rewrite request headers per-endpoint with set / append / remove semantics, including a couple of template variables for dynamic hosts.

Header rules attach to an endpoint and apply to every request that matches it. They run before the request reaches your local server (and before LocalCan's tunnel forwards it across the public edge).

Short syntax

For a one-off set, write the header inline as "Name: value":

YAML

endpoints:
  - url: api.local
    headers:
      - "Host: api.example.com"
      - "X-Forwarded-Proto: https"

Short-syntax entries always use mode: set and are always enabled.

Long syntax

Use the long form when you need any of mode, enabled, or template variables:

YAML

endpoints:
  - provider: localcan
    headers:
      - name: Host
        value: "{{target_host}}"
        mode: set
      - name: X-Trace-ID
        value: "{{original_host}}"
        mode: append
      - name: X-Powered-By
        mode: remove
      - name: Cookie
        value: session=preview
        mode: set
        enabled: false

Key	Type	Default	Notes
`name`	string	—	Header name. Required.
`value`	string	`""`	New value. Ignored when `mode: remove`.
`mode`	string	`set`	`set`, `append`, or `remove`.
`enabled`	bool	`true`	Disable a rule without deleting it.

Modes

set: replace any existing value (or add the header if it wasn't there).
append: add a new value without removing existing ones. Useful for headers that legitimately appear multiple times (Set-Cookie, X-Forwarded-For, custom tracing headers).
remove: strip the header from the request. value is ignored.

Template variables

Header values may contain {{variable}} placeholders that are resolved per-request:

Variable	Value
`{{target_host}}`	Hostname from the service `target` (e.g. `localhost` for `http://localhost:3000`).
`{{original_host}}`	The `Host` header the client sent before LocalCan rewrote it.

Unknown variables resolve to the empty string. Literal {{ followed by }} with nothing between is treated as the literal text {{}}.

Headers LocalCan adds

LocalCan adds these headers to every request it forwards through a Public URL. Your header rules run after them, so a set or remove rule can change or drop any of them.

Header	Value
`X-Forwarded-For`	The visitor's IP address
`X-Real-IP`	The visitor's IP address, same as `X-Forwarded-For`
`X-Forwarded-Host`	The public hostname the visitor requested
`X-Forwarded-Proto`	`https`
`X-Forwarded-Port`	`443`
`LC-IPCountry`	The visitor's country as a two-letter ISO 3166-1 code, such as `US` or `PL`. Left out when LocalCan can't tell the country

LocalCan's servers take the visitor's IP and country from the connection itself and drop any value the visitor sent in these headers, so your app can trust them on requests that arrive through a Public URL. Header names are case-insensitive, and many frameworks show them in lower case (x-real-ip, lc-ipcountry).

On a .local domain, LocalCan adds X-Forwarded-For, X-Forwarded-Host, X-Forwarded-Proto (http or https, matching the request) and X-Forwarded-Port (the local proxy's port). X-Real-IP and LC-IPCountry come only through Public URLs.

Common recipes

Make your local app think it's hosted on its production hostname:

YAML

headers:
  - "Host: app.example.com"

Forward the Public URL's host to the local app for SaaS-style multi-tenancy testing:

YAML

endpoints:
  - provider: localcan
    headers:
      - name: Host
        value: "{{original_host}}"
        mode: set

Strip a debug header your local server adds, before it reaches the public internet:

YAML

headers:
  - name: X-Debug-Tokens
    mode: remove