Customer subpaths

Download the server adapter and save it as proxy.ts in your server project. This is TypeScript source for your backend; do not import it into browser code.

Pages still runs in Chatbyte's shared Pages project. The customer's website routes https://acme.com/support through its own server or edge proxy. DNS cannot route a path. This integration shares the customer's browser origin and therefore requires a trusted server configuration, even for a public Page.

Configure the connection

1. In Agent → Deployments → Pages → Domains, enter the customer hostname and a path such as /support or /help/support.
2. Copy the connection ID and the one-time proxy key into the customer's server secret store. The database stores only its hash. Replace proxy key invalidates the old key immediately and requires verification again.
3. Add the displayed _chatbyte-pages ownership TXT record. Keep the customer's existing website DNS/TLS; this connection does not attach its domain to our Vercel project.
4. Install the adapter below, routing both the exact mount and its descendants, plus /_chatbyte-pages-assets/*. The asset prefix is deliberately separate from the customer's own /_next files. Route the asset prefix to the same Pages deployment as the document. If Pages uses an explicit asset CDN instead, allow that origin in the customer's CSP.
5. Verify the connection, or wait for the automatic check. Verification checks the TXT record and a nonce-bound readiness response authenticated by the proxy connection. A static fake health response cannot verify the connection.
6. Publish the Page. The customer can select the subpath as its primary address.

Use the Pages gateway origin for the matching environment, for example https://www.chatbyte.page. Do not point the gateway back at the customer proxy. The Chatbyte base hostname needs to be attached to the Pages project in addition to its tenant wildcard. The base hostname can serve gateway routes without being a published customer Page.

Cloudflare Worker or Fetch-compatible server

Copy proxy.ts into the customer server project. It uses standard Request/Response streams and does not import Chatbyte's monorepo packages.

import { createPageProxy } from './proxy';

interface ProxyEnvironment {
  CHATBYTE_PAGES_PROXY_KEY: string;
}

export default {
  fetch(request: Request, env: ProxyEnvironment) {
    return createPageProxy({
      publicOrigin: 'https://acme.com',
      pathPrefix: '/support',
      gatewayOrigin: 'https://www.chatbyte.page',
      domainId: '<connection-id>',
      pageSurfaceId: '<page-surface-id>',
      proxyKey: env.CHATBYTE_PAGES_PROXY_KEY,
      // Cloudflare supplies this field. On other hosts use their trusted metadata.
      clientAddress: (request) => request.headers.get('CF-Connecting-IP'),
    })(request);
  },
};

Configure Worker routes for acme.com/support* and acme.com/_chatbyte-pages-assets/*. The adapter rejects sibling paths such as /support-other; use exact route exclusions or invoke it from the website's existing router if those paths exist. The adapter validates the public origin, preserves streaming and cancellation, and does not cache Page documents or APIs. Keep proxy timeouts compatible with the Pages 300-second streaming limit.

The adapter streams Fetch's decoded response body and removes stale compression and length headers when a body is present. HEAD/304 representation metadata stays intact. A custom fetchUpstream must retain Fetch's automatic decompression; do not disable it or supply raw compressed bytes. Compression on the customer-facing connection can be handled by the customer's host/CDN.

The proxy strips application cookies, Authorization and arbitrary forwarding headers. It forwards only this Page's host-only cookie or its dedicated X-Pages-Session credential. Client IP forwarding is optional and must come from trusted hosting metadata. A user-supplied X-Forwarded-For is not an identity.

Hosted login still uses the backend login bridge. Sharing a hostname does not authenticate the user. The backend still derives subject, account and roles from the real customer session and signs the proof. Never put the proxy key, RSA private key, or customer's IdP access tokens in browser JavaScript. The public Pages SDK remains at /pages.min.js on the CDN.

Acceptance and recovery

The browser suite runs this adapter against the production Pages build and a disposable database. It covers private sign-in, assets, history, reload and proxy revocation; adapter tests check credential stripping, incremental streams, and gzip/deflate/Brotli responses through real local HTTP gateway and proxy servers. Deploying a real Worker/server and testing its WAF, platform timeouts, DNS/TLS and customer login remains a hosted acceptance gate.

If setup fails, inspect the domain card's error and next-check time. Verify is an immediate retry; automated retries back off from five minutes to six hours. Remove revokes local routing first. A lost key can be replaced; the secret is not retrievable. Do not disable hostname, path, Page ID or origin checks to get a proxy working.

Routing and redirects

The adapter's server-held connection ID/key selects the registered hostname and mount. Arbitrary Forwarded/X-Forwarded-Host or X-Pages-Host values are not a routing mechanism. For direct-domain hosting, preserve Host and the correct request scheme at your ingress; Vercel supplies the public domain in Host automatically.

Pages normalizes trailing slashes only after validating the routing context. The adapter keeps valid redirects on your public origin and mount, including queries/fragments; sibling paths and foreign origins fail closed. Preserve the adapter's manual redirect handling and streaming response body. Server-Timing headers measure Pages ingress work; API and asset requests still validate the proxy key but skip document framing-policy reads.