DNS Proxy Quickstart

The DNS proxy lets you add PerfectSearch to any website with zero code changes. Instead of installing a middleware package, you point your domain's DNS to the PerfectSearch edge network. Bot traffic is automatically separated and served pre-rendered snapshots, while human visitors are reverse-proxied to your origin server with no perceptible difference. This works with any JavaScript framework including React, Vue, Angular, Svelte, Astro, and static site generators.

What is the DNS proxy?

The DNS proxy is a high-performance Go reverse proxy running on Fly.io's global edge network. When a request arrives, the proxy inspects the User-Agent header to determine whether the visitor is a human or a bot. Human traffic is transparently reverse-proxied to your origin server with streaming responses. Bot traffic is routed to the PerfectSearch Snapshot API and served pre-rendered content.

• Runs on Fly.io with edge nodes in 30+ regions worldwide
• Sub-millisecond bot detection — no latency impact for human visitors
• Streams responses without buffering the full body
• Automatic TLS certificate provisioning for your custom domain

How do I add my site?

Start by creating a new site in the PerfectSearch dashboard. During setup, select "DNS Proxy" as the integration mode and enter your production domain. The dashboard will generate a unique CNAME target and display the origin URL field where you will enter your actual server address in a later step.

1. Log in to the PerfectSearch dashboard
2. Click Add Site and enter your domain (e.g., example.com)
3. Select DNS Proxy as the integration mode
4. Note the CNAME target shown — you will use this in the next step

How do I configure my CNAME record?

Add a CNAME record in your DNS provider that points your domain to the PerfectSearch edge network. This routes all traffic through the proxy, which handles bot detection and separation automatically. The CNAME target follows the pattern yourdomain.edge.perfectline.io, and the exact value is shown in your dashboard after creating the site.

Type:  CNAME
Name:  yourdomain.com
Value: yourdomain.edge.perfectline.io

DNS provider instructions

• Cloudflare — Add the CNAME record and set the proxy status to "DNS only" (gray cloud). Orange-cloud proxying will conflict with PerfectSearch.
• Namecheap — Go to Advanced DNS, add a new CNAME record with the host and target values.
• Route 53 — Create a CNAME record set in the hosted zone for your domain.
• GoDaddy — Go to DNS Management and add a CNAME record with the appropriate values.

DNS propagation typically takes 5 to 30 minutes but can take up to 48 hours with some providers.

How do I set my origin URL?

The origin URL tells the PerfectSearch proxy where to forward human visitor traffic. This is the actual server URL where your site is hosted. Set it in the PerfectSearch dashboard under your site's Settings page. For Vercel deployments, use your .vercel.app URL. For other providers, use whatever URL serves your site before the CNAME redirect.

# Vercel
https://my-app-abc123.vercel.app

# Netlify
https://my-app.netlify.app

# Railway
https://my-app.up.railway.app

# Self-hosted
https://origin.example.com

How does TLS work?

TLS certificates are provisioned automatically using CertMagic and Let's Encrypt. When the first request arrives at the proxy for your domain, a certificate is requested and issued on the fly. This initial request may take 5 to 30 seconds to complete while the certificate is being provisioned. All subsequent requests use the cached certificate with zero additional latency.

• Certificates are issued via Let's Encrypt (ACME HTTP-01 challenge)
• Renewals happen automatically 30 days before expiry
• No manual certificate management required
• Supports both apex domains and subdomains

How do I verify the setup?

Once your CNAME record has propagated and the TLS certificate has been provisioned, use the PerfectSearch Visibility Test tool to confirm that bot traffic is being intercepted and served pre-rendered snapshots. The tool shows you exactly what search engines and AI crawlers see when they visit your pages, including response headers and content format.

Open the Visibility Test tool →

You can also verify by checking the response headers. Requests routed through the proxy will include an x-perfectsearch: hit header when a cached snapshot is served, or x-perfectsearch: miss when the page is queued for rendering.