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 {{}}.

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