Cloudflare Deploy And Access

Purpose

This document is the operator reference for Cloudflare deployment targets, custom domains, Access boundaries, API docs exposure, and early AI/MCP safety rules. It records intended topology and review rules only. It does not create Cloudflare resources, Access policies, DNS records, Worker routes, Pages projects, API tokens, OAuth credentials, account IDs, zone IDs, or secrets.

Domain Plan

Subdomains are infrastructure entrypoints, not long-term app identity. OS apps still use manifest-driven IDs and route groups inside the shell.

Deployment Scripts

Run deploy commands only after reviewing the target Cloudflare account, Pages project, Worker, custom domain, and Access policy in the Cloudflare dashboard.

Docs deployment (static export)

apps/docs uses Next.js output: 'export' and deploys the out/ directory to Cloudflare Pages (prox-os-docs, target host docs.prox-os.com). Search, llms.txt, Open Graph images, and markdown export routes are pre-rendered at build time (Fumadocs static Orama for /api/search). The proxy.ts markdown negotiation helper runs in local dev only; on the static site use /llms.mdx/docs/.../content.md URLs directly.

If the docs site later needs SSR or dynamic server routes beyond static export, migrate to OpenNext on Cloudflare Workers instead of expanding the Pages artifact hack.

API Worker Routes

Local development:

http://localhost:8787/docs
http://localhost:8787/openapi.json
http://localhost:8787/health

Production target:

https://api.prox-os.com/docs
https://api.prox-os.com/openapi.json
https://api.prox-os.com/health

The Worker config includes a reviewable custom-domain route placeholder:

api.prox-os.com -> apps/api-worker Worker

Wrangler custom domains are host-level routes: the host serves all paths under api.prox-os.com, including /health, /openapi.json, and /docs.

Do not add docs.api.prox-os.com for the current phase.

Public And Protected Boundaries

Recommended public early surfaces:

prox-os.com
prox-os.com/*
docs.prox-os.com
docs.prox-os.com/*
api.prox-os.com/health
api.prox-os.com/robots.txt

Recommended Cloudflare Access-protected early surfaces:

ui.prox-os.com/*
api.prox-os.com/docs
api.prox-os.com/openapi.json
api.prox-os.com/scalar
api.prox-os.com/internal/*

/docs and /openapi.json can be deployed, but they should not be exposed bare to the public in early development. API docs are not automatically dangerous, but they reveal endpoint structure, product direction, permission models, and unstable data shapes. Restrict them to a personal email or a small team allowlist with Cloudflare Access until the public API contract is stable.

No docs.api.prox-os.com

The current API documentation surface is:

api.prox-os.com/docs

Protected OpenAPI schema:

api.prox-os.com/openapi.json

Do not create docs.api.prox-os.com unless API documentation becomes a standalone developer portal with its own release cadence, authentication, billing, or external developer experience.

Future API Docs Split

Internal API docs:

• api.prox-os.com/docs
• api.prox-os.com/openapi.json
• Full schema
• Internal endpoints
• Debug endpoints
• Admin endpoints
• Protected by Cloudflare Access

External API docs:

• docs.prox-os.com/api
• Or a future standalone developer portal
• Stable public API only
• Internal, admin, and debug endpoints hidden
• Designed for community developers and third-party app developers

AI And MCP Safety

Early AI integrations are read-only by default.

• Do not grant AI write permissions in early development.
• Do not let AI directly mutate DNS, WAF rules, Access policies, Worker routes, Pages projects, secrets, or production environment variables.
• AI may generate proposals, diffs, configuration notes, and review checklists. Humans must review and apply them.
• Real Cloudflare API tokens, OAuth credentials, .env.local, .dev.vars, account IDs, zone IDs, and secrets must not be committed.
• Prefer official MCP servers or trusted providers. Do not use unknown third-party MCP proxies for Cloudflare, GitHub, database, or observability access.

Future Product Surface

These capabilities should eventually move into the Prox OS System Monitor and AI Console apps:

• Cloudflare Analytics
• Cloudflare Security Events
• Workers logs
• API health
• App product events
• MCP catalog
• AI-generated monitoring insights
• Human-approved Cloudflare rule suggestions

Manual Cloudflare Follow-up

Before production use, a human operator should:

1. Create or verify Pages projects prox-os, prox-os-docs, prox-os-ui-workshop, and esmadrider-me.
2. Create or verify the Worker prox-os-api-worker.
3. Attach custom domains prox-os.com, docs.prox-os.com, ui.prox-os.com, and api.prox-os.com.
4. Add Cloudflare Access policies for UI Workshop and API docs/internal routes.
5. Keep all API tokens, OAuth credentials, account IDs, zone IDs, and secrets outside the repository.
6. Verify API docs exposure from a signed-in Access session and from a public anonymous browser session.

External References

• Cloudflare Workers Next.js guide
• Cloudflare Pages Next.js guide