Remote paths

Remote paths let a Fern-hosted docs domain serve part of its URL space from another application. Fern serves the docs site and reverse-proxies each configured path prefix to an HTTPS service you run. For example, developer.example.com can serve docs from Fern and a developer portal at developer.example.com/ui from your own app.

Remote paths are the inverse of a reverse proxy setup, where your infrastructure owns the domain and forwards a subpath to Fern. With remote paths, Fern owns the domain and forwards a subpath to you, so no proxy rules are needed on your side.

Configure remote paths

Add a remote-paths list to docs.yml. Each entry maps a path on your docs domain to a destination URL:

remote-paths:
  - path: /ui
    destination: https://portal.example.com/ui

Remote paths take effect when you publish your docs, and preview builds include them. Rolling back to an earlier deployment also rolls back its remote paths. A site can have up to 20 remote paths.

Matching

A remote path matches its own URL and everything beneath it, on whole path segments. With path: /ui:

The destination path doesn’t need to match path. With destination: https://portal.example.com, a request to /ui/applications goes to https://portal.example.com/applications.

Remote paths take precedence over redirects and docs pages, so a page under a remote path is never served. Fern’s own endpoints, such as /_fern-files, /api/fern-docs, /.well-known, /robots.txt, /sitemap.xml, and /llms.txt, always stay with Fern, and fern check rejects a path that overlaps one of them. Two remote paths can’t overlap each other.

Allowed destinations

fern check rejects a destination that isn’t a public HTTPS host:

• Not https, has a port, credentials, a query string, or a fragment.
• An IP address, localhost, a single-label hostname, or a private suffix such as .local or .internal.
• A host Fern serves, including *.buildwithfern.com, *.ferndocs.com, and your own docs domains.

The destination must answer on its own hostname with a valid TLS certificate. Fern sends the destination’s hostname as Host and passes your docs domain in X-Forwarded-Host.

Request and response handling

Fern forwards every HTTP method, the request body, and websocket upgrades. Responses, including server-sent events and other streamed responses, pass through without buffering.

• Headers: Fern adds X-Forwarded-Host, X-Forwarded-Proto, X-Forwarded-For, and Forwarded.
• Redirects: Fern returns redirects to the browser instead of following them. A Location that points at the destination is rewritten to the matching path on your docs domain, so https://portal.example.com/ui/logout becomes /ui/logout.
• Cookies: cookies your app sets are scoped to your docs domain and to the remote path. A cookie scoped to an upstream path outside the destination is dropped. __Host- cookies keep Path=/, which their prefix requires.
• Caching: Fern never caches proxied responses. Your app’s Cache-Control headers reach the browser unchanged.
• Errors: your app’s error responses pass through. If Fern can’t reach the destination, it returns 502 Bad Gateway.

Authentication

Remote paths aren’t covered by docs authentication. Fern doesn’t check a visitor’s docs login before proxying and doesn’t forward Fern’s login cookies, so your app handles its own authentication.