Operations

Local API

The host-side control API is local-socket-only by default on macOS and Linux. That is a deliberate security posture, not an omission.

Current routes include:

• GET /health
• GET /version
• GET /status
• GET /stats
• GET /leases
• GET /forwards
• POST /forwards
• DELETE /forwards
• POST /admin/drain
• upstream-compatible forwarder alias routes
• /tunnel and /connect

For the full contract, use the repository docs in docs/api.md.

Native backend smoke

The repo already has host-native smoke entrypoints for:

• VZ / vfkit on macOS
• Firecracker-compatible flows on Linux

Use:

just real-smoke-help
just vz-smoke-prepare
just real-vz-traffic-smoke
just firecracker-smoke-prepare
just real-firecracker-traffic-smoke

Practical execution rule:

• use native macOS runs for VZ/vfkit production evidence
• use Lima on macOS for Firecracker development loops
• do not treat Lima Firecracker runs as final parity proof

Byte audit coverage

The current audit export path covers:

• per-VM packet transport bytes
• local API socket bytes
• /tunnel relay bytes on both the Unix and TCP sides

See docs/api.md and docs/security.md for the export format and retention guidance.

Capturing release evidence

Do not rely on terminal history for release-proof runs. Use the evidence capture wrapper:

just capture-vz-traffic-proof
just capture-firecracker-traffic-proof

Or directly:

sh scripts/capture-production-evidence.sh <backend> <scenario> [command...]

Artifacts land in:

artifacts/production-evidence/

Each capture writes:

• summary.md
• command.log

That is the expected path for smoke, cutover, and throughput evidence.

Docs site deployment

The docs site is built from site/ and deployed by the GitHub Actions workflow:

.github/workflows/deploy-docs-site.yml

That workflow:

• installs site dependencies
• runs npm run check
• runs npm run build
• ensures the Cloudflare Pages project exists
• deploys site/dist

Required GitHub Actions configuration:

• secret: CLOUDFLARE_ACCOUNT_ID
• secret: CLOUDFLARE_API_TOKEN
• secret or variable: CLOUDFLARE_PAGES_PROJECT
• secret or variable: DOCS_SITE_URL

The workflow accepts CLOUDFLARE_PAGES_PROJECT and DOCS_SITE_URL from either Actions variables or Actions secrets. Secrets take over cleanly if variables are not present.

One practical distinction matters:

• *.workers.dev is a Worker hostname
• *.pages.dev is a Pages hostname

If the docs are being deployed by this workflow, the deployment target is the Cloudflare Pages project named by CLOUDFLARE_PAGES_PROJECT. If you want a custom production hostname, attach it to that Pages project in Cloudflare.