mintlify__docs/deploy/reverse-proxy.mdx

---
title: "Reverse proxy"
description: "Configure a custom reverse proxy with nginx or a similar tool to serve your Mintlify documentation at a subpath on your own domain."
keywords: ["reverse proxy configuration","nginx","proxy routing","header forwarding"]
---

import SubpathSetupSteps from "/snippets/subpath-setup-steps.mdx";

To serve your documentation through a custom reverse proxy, you must configure routing rules, caching policies, and header forwarding.

When you implement a reverse proxy, monitor for potential issues with domain verification, SSL certificate provisioning, authentication flows, performance, and analytics tracking.

## Set your base path

Set your base path on the [Custom domain setup](https://app.mintlify.com/settings/deployment/custom-domain) page in your dashboard. Then configure your reverse proxy to route that path to Mintlify. The default base path is `/docs`, but you can use any base path you choose, like `/help` or `/resources`.

The directory that contains your documentation in your repository does not configure the public base path. For example, storing documentation under a `/docs` directory does not replace setting `/docs` as the base path in your dashboard.

In all configurations, use `mintlify.site` as the proxy target.

## Host at `/docs` subpath

Use this configuration when you want to serve documentation at the `/docs` path on your domain.

Before configuring your reverse proxy:

1. Navigate to [Custom domain setup](https://app.mintlify.com/settings/deployment/custom-domain) in your dashboard.
2. Enable the **Host at** toggle.
3. Enter your domain.
4. Enter `docs` as your base path.
5. Click **Add domain**.

<Warning>
  When you host at a subpath, your canonical docs URL becomes `<your-subdomain>.mintlify.site<your-base-path>`, like `<your-subdomain>.mintlify.site/docs`. Proxy to `<your-subdomain>.mintlify.site` so cache invalidation and updates take effect.
</Warning>

### Routing configuration

Proxy these paths to your Mintlify subdomain:

| Path                              | Destination                          | Caching  |
| --------------------------------- | ------------------------------------ | -------- |
| `/docs`                           | `<your-subdomain>.mintlify.site/docs` | No cache |
| `/docs/*`                         | `<your-subdomain>.mintlify.site/docs/*` | No cache |
| `/docs/_llms/*`                   | `<your-subdomain>.mintlify.site/docs/_llms/*` | No cache |
| `/.well-known/vercel/*`           | `<your-subdomain>.mintlify.site/.well-known/vercel/*` | No cache |
| `/.well-known/skills/*` (optional)        | `<your-subdomain>.mintlify.site/docs/.well-known/skills/*` | No cache |
| `/.well-known/agent-skills/*` (optional)  | `<your-subdomain>.mintlify.site/docs/.well-known/agent-skills/*` | No cache |
| `/skill.md` (optional)                    | `<your-subdomain>.mintlify.site/docs/skill.md` | No cache |
| `/llms.txt` (optional)            | `<your-subdomain>.mintlify.site/docs/llms.txt` | No cache |
| `/llms-full.txt` (optional)       | `<your-subdomain>.mintlify.site/docs/llms-full.txt` | No cache |

Your proxy must forward all HTTP methods on documentation paths. Mintlify sends analytics events as `POST` requests to `/docs/_mintlify/api/v1/e`. A proxy that only allows `GET` and `HEAD` requests silently breaks the analytics in your dashboard.

Mintlify serves these files under your base path, like `<your-subdomain>.mintlify.site/docs/llms.txt`. They are available on your domain under your subpath, like `your-domain.com/docs/llms.txt`, through your main subpath route.

The `/docs/*` route also covers generated `llms.txt` indexes under `/docs/_llms/*`. If your proxy uses a more granular path allowlist instead of forwarding all `/docs/*` requests, include `/docs/_llms/*` so agents can follow every index linked from `/docs/llms.txt`.

Do not rewrite only `/docs/llms.txt` to a root-hosted `/llms.txt`. Set `/docs` as the deployment base path and forward the full `/docs/*` route. This keeps page links and generated `/docs/_llms/*` index links on the same public prefix.

The `/.well-known/skills/*`, `/.well-known/agent-skills/*`, `/skill.md`, `/llms.txt`, and `/llms-full.txt` routes are optional. Include them only if you also want to serve these files at root paths on your domain, like `your-domain.com/llms.txt`. Each root path maps to the file under your base path on your Mintlify subdomain.

### Required header configuration

Configure your reverse proxy with these header requirements:

- **Origin**: Contains the target subdomain `<your-subdomain>.mintlify.site`.
- **X-Forwarded-For**: Preserves client IP information.
- **X-Forwarded-Proto**: Preserves the original protocol (HTTP/HTTPS).
- **X-Real-IP**: Forwards the real client IP address.
- **User-Agent**: Forwards the user agent.

<Warning>
  Do not forward the `Host` header.
</Warning>

### Example nginx configuration

```nginx
server {
    listen 80;
    server_name <your-domain>.com;

    # Vercel verification paths
    location ~ ^/\.well-known/vercel/ {
        proxy_pass https://<your-subdomain>.mintlify.site;
        proxy_set_header Origin <your-subdomain>.mintlify.site;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header User-Agent $http_user_agent;

        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    # AI skills paths
    location ^~ /.well-known/skills/ {
        proxy_pass https://<your-subdomain>.mintlify.site/docs/.well-known/skills/;
        proxy_set_header Origin <your-subdomain>.mintlify.site;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header User-Agent $http_user_agent;

        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    # Agent-skills discovery paths
    location ^~ /.well-known/agent-skills/ {
        proxy_pass https://<your-subdomain>.mintlify.site/docs/.well-known/agent-skills/;
        proxy_set_header Origin <your-subdomain>.mintlify.site;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header User-Agent $http_user_agent;

        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    # Skill manifest (optional)
    location = /skill.md {
        proxy_pass https://<your-subdomain>.mintlify.site/docs/skill.md;
        proxy_set_header Origin <your-subdomain>.mintlify.site;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header User-Agent $http_user_agent;

        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    # LLM index files (optional)
    location = /llms.txt {
        proxy_pass https://<your-subdomain>.mintlify.site/docs/llms.txt;
        proxy_set_header Origin <your-subdomain>.mintlify.site;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header User-Agent $http_user_agent;

        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    location = /llms-full.txt {
        proxy_pass https://<your-subdomain>.mintlify.site/docs/llms-full.txt;
        proxy_set_header Origin <your-subdomain>.mintlify.site;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header User-Agent $http_user_agent;

        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    # Documentation root
    location = /docs {
        proxy_pass https://<your-subdomain>.mintlify.site;
        proxy_set_header Origin <your-subdomain>.mintlify.site;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header User-Agent $http_user_agent;

        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    # All documentation paths
    location /docs/ {
        proxy_pass https://<your-subdomain>.mintlify.site/docs/;
        proxy_set_header Origin <your-subdomain>.mintlify.site;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header User-Agent $http_user_agent;

        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }
}
```

## Custom subpath

To use a subpath other than `/docs` (such as `/help` or `/resources`):

<SubpathSetupSteps />

Mintlify rebuilds your documentation to serve at your base path, so `<your-subdomain>.mintlify.site<your-base-path>` serves your content.

Configure your reverse proxy using the same [routing configuration](#routing-configuration), [header requirements](#required-header-configuration), and nginx patterns as the `/docs` subpath, replacing `/docs` with your base path.

## Troubleshooting

### Changes not appearing

**Symptoms**: You publish documentation updates, but the changes don't appear on your site.

**Cause**: Your reverse proxy points to an outdated hostname.

**Solution**: Update your reverse proxy configuration to point to `<your-subdomain>.mintlify.site`.

### 404 error

**Symptoms**: Documentation loads, but features don't work. API calls fail.

**Cause**: The reverse proxy forwards the `Host` header or the `Origin` header is missing.

**Solution**:

- Remove `Host` header forwarding.
- Set the `Origin` header to your Mintlify subdomain (`<your-subdomain>.mintlify.site`).

### Generated `/_llms/` links return 404

**Symptoms**: Your `llms.txt` file loads, but links under `/_llms/` return 404 or omit your public subpath.

**Cause**: The public subpath does not match the base path configured in Mintlify, or the proxy only forwards `llms.txt` and not its generated index routes.

**Solution**:

- Set the public subpath as the base path in your Mintlify dashboard. A repository directory with the same name does not configure it.
- Forward the full `<base-path>/*` route, or add `<base-path>/_llms/*` to a granular allowlist.
- Redeploy your documentation, then verify both `<base-path>/llms.txt` and one linked `<base-path>/_llms/*.md` URL.

### Performance issues

**Symptoms**: Slow page loads and layout shifts.

**Cause**: Incorrect caching configuration.

**Solution**: Disable caching for documentation paths. If you proxy `/mintlify-assets/_next/static/*` paths, enable caching only for those static assets.