# Reverse proxy (/deploy/reverse-proxy)

<!-- agent-signals: reading_time_min: 5 · est_tokens: 2479 · updated: 2026-07-30 -->
Related: [Host docs at a subpath](/deploy/docs-subpath.md), [Deploy at a subpath with Cloudflare Workers](/deploy/cloudflare.md), [Deploy at a subpath with AWS Route 53 and CloudFront](/deploy/route53-cloudfront.md), [Deploy at a subpath with Vercel](/deploy/vercel.md), [Content Security Policy (CSP) configuration](/deploy/csp-configuration.md)

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]

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`.

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

## Host at `/docs` subpath [#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 [#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 |
| `/.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`, so 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`, so they are available on your domain under your subpath, like `your-domain.com/docs/llms.txt`, through your main subpath route.

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`. Note that each root path maps to the file under your base path on your Mintlify subdomain.

### Required header configuration [#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 [#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 [#custom-subpath]

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

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

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 [#troubleshooting]

### Changes not appearing [#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 [#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`).

### Performance issues [#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.