Reverse Proxy & Routing Rules

Last updated

Reverse-proxy paths on your domain to Ploy pages or external origins — no full migration required.

Ploy ships a built-in reverse proxy at the edge of your domain. You point DNS at Ploy, and Ploy decides per-request whether to serve an AI-built Ploy page, forward the request to an external origin (Webflow, Vercel, Cloudflare, AWS, Google Cloud Run, your own app), or redirect. Visitors see a single, unified site; behind the scenes, traffic is split across as many backends as you want.

The split is controlled by Routing Rules — the configuration layer for the reverse proxy. Each rule matches an incoming request by path prefix or regex and dispatches it to a Ploy site, proxies it to an external origin, or issues a redirect. Rules are evaluated top-to-bottom; the first match wins.

The walkthrough below uses specific Ploy page rules and a separate Default fallback proxy for unmatched paths. Origin providers can have different hostname and HTTPS requirements. See Fallback Origins for background, then check your provider's requirements and test your configuration before moving production traffic.

To manage the complete routing document from the command line, use ploy site routing get and ploy site routing set. See Routing rules in the Ploy CLI for hostname selection, dry runs, and safe replacement behavior.

How Routing Rules Work

When you point your domain’s DNS to Ploy, all incoming traffic flows through Ploy’s edge network first. Ploy then decides where to send each request based on the routing rules you’ve configured:

Rule TypeActionDescription
Path PrefixPloy siteMatches any request whose path starts with the given prefix. Routes to a specific Ploy-built site.
RegexProxyMatches requests using a regular expression pattern. Proxies the request to an external origin URL (e.g. your Webflow site).

Key concept: Rules are evaluated top-to-bottom. The first matching rule wins. Keep specific path rules before broader rules. In this walkthrough, requests that match no rule go to the separate Default fallback proxy. The fallback is not another row in the rule list.

Prepare a routing change with Ploy

Your plan must support a custom domain. Applying routing changes requires an Admin or Owner; an additional confirmation may be required.

To find the current rules, open Sites, select the site, open Hosting, select the domain, then choose Manage. You can edit rules there manually, or ask Ploy to prepare a proposal in a conversation. A proposal is not saved immediately.

  1. Request the change in a chat. Name the domain and the paths you want to change.
  2. Open Review changes in the conversation card.
  3. Examine the differences and confirm the affected domain.
  4. Choose Apply Changes only if the proposal is correct. Complete any additional confirmation shown.
  5. Wait for the change to finish, then return to the domain's Manage view and confirm the saved rules.
  6. Test the affected public paths, including pages and assets that should remain unchanged.

If the rules changed after the proposal was prepared, request a fresh proposal. If the UI says applying the change has not fully completed, do not assume visitors are already seeing the new routing.

Step-by-Step Setup

Follow these steps on a test domain before changing production routing. Your plan must support custom domains, and an Admin or Owner must apply the changes.

Step 1: Set up your origin host

Your existing site needs a stable HTTPS origin URL, such as https://origin.example.com, that continues to serve it after you change routing. Confirm the origin URL and hostname requirements with your provider. Test that the origin serves the expected pages and assets.

See Fallback Origins for per-provider instructions — Webflow, Vercel, Cloudflare Pages/Workers, AWS, Google Cloud Run, and more. Come back here once your origin is serving traffic over HTTPS.

Step 2: Add a Test Domain in Ploy

Before moving your production domain, set up a test subdomain so you can verify everything works.

  1. Open Sites, select your site, then open Hosting.
  2. Add a test subdomain, such as ploy-test.example.com.
  3. Follow the records shown for that test domain. See Custom Domain Setup for the domain-connection steps.
  4. Wait until the domain's status confirms it is ready before testing routing.

Step 3: Configure Routing Rules

Open Sites, select the site, open Hosting, select the test domain, then choose Manage.

  1. Add a Path Prefix rule for each path Ploy should serve. Choose Ploy site as the action and select the site containing the page.
  2. Check the asset paths used by those pages. If their styles, scripts, images, or fonts need their own Ploy rules, add rules for those actual paths. Do not assume every site uses the same asset directory.
  3. Keep specific rules before broader ones. The first matching rule wins.
  4. Enable the separate Default fallback proxy control and enter the HTTPS origin URL for your existing site. This handles paths that match none of the rules above.
  5. Set Preserve Host header according to your origin provider's requirements. Check the guidance shown in the control and verify the choice on the test domain.

This walkthrough uses Default fallback proxy, not a catch-all rule. Do not add a catch-all rule as an extra step.

Example configuration

ControlExampleExpected result
Path Prefix rule/experience, with action Ploy site and your site selectedMatching requests go to the Ploy site.
Additional Ploy rules, if neededThe actual paths used by the Ploy page's assetsThose files load from the intended site.
Default fallback proxy, outside the rule listhttps://origin.example.comUnmatched requests go to the existing site's origin.

Preserve Host header controls whether the original request's hostname is passed to the origin. There is no universal choice for every provider. Do not assume that turning it on or off is correct for Webflow or another host without checking that provider's requirements and testing the result.

Step 4: Save and review

  1. After editing, choose Save Rules.
  2. Review the displayed changes and confirm the affected domain, rule order, selected Ploy site, fallback origin, and Host-header choice.
  3. Choose Apply Changes only if the changes are correct. Complete any additional confirmation shown.
  4. Wait for the change to finish. If the UI says it has not fully completed, do not assume the new routing is live.
  5. Return to the domain's Manage view and confirm the saved configuration.

If the rules changed while you were reviewing them, return to the current configuration and review fresh changes before applying. Do not approve an outdated proposal.

Step 5: Test both paths and their assets

  1. Open the Ploy path on the test domain, such as https://ploy-test.example.com/experience. Confirm that it shows the intended Ploy page.
  2. Open a known existing-site path that matches none of the Ploy rules. Confirm that it shows the expected content from the fallback origin.
  3. Check both pages' styles, scripts, images, and fonts. Exercise their important links and interactions, stopping before any action that would submit data or make a change.
  4. If either path fails, review the matching rules, fallback origin, and provider requirements before moving production traffic.

If a page loads without its assets, check the files' actual request paths rather than adding a broad rule that could take traffic away from your existing site.

Step 6: Prepare the production domain

Only move production traffic after the test-domain checks pass. Follow Custom Domain Setup using the records shown for the production domain, not assumed copies of the test domain's records.

Review the production domain's rules and Default fallback proxy separately. Repeat Save and review, then test both the Ploy and existing-site paths and their assets on the public production domain. Keep the origin available while any traffic still depends on it.

FAQ

Does my existing site need to stay hosted?

Yes, while the fallback proxy sends traffic to it. Routing does not replace your existing site's hosting. Keep its origin available and check both sets of pages before and after a routing change.

Can I add more Ploy pages later?

Yes. Add specific Path Prefix rules for the new pages and any required assets, review and apply the changes, then test them. Unmatched paths continue to use the configured Default fallback proxy.

What if I want to migrate my entire site to Ploy?

First check that Ploy has the pages, assets, and behavior you need to replace the existing site. Plan and review the routing change separately before disabling the fallback. Do not remove the old origin while pages or assets still rely on it.

Does order matter for the rules?

Yes. Rules are evaluated top-to-bottom, and the first match wins. Keep specific rules before broader ones. Default fallback proxy applies only when no rule matches.

What’s Next?