Self-hosted control plane prerequisites and LLM operator runbook

[mathaix]

Goal

Document and enable a self-hosted/local OCM control plane that preserves the hosted architecture: Cloudflare Tunnel, Cloudflare Worker/KV data plane, Firebase or Cloudflare Access human auth, OCM-issued ocm_token, KVM host enrollment, and Firecracker VM runtime.

This is not a separate localhost-only architecture. The self-hosted control plane should behave like the hosted control plane, using the operator’s domain, Cloudflare account, auth provider, and registered KVM workers.

Target flow

1. Operator deploys OCM control plane on any machine.
2. Operator configures Cloudflare DNS, Tunnel, Worker, KV, and wildcard routing.
3. Operator configures Firebase auth or Cloudflare Access.
4. Admin logs into OCM.
5. Admin creates an enrollment token for a KVM host.
6. KVM host registers as a worker through OCM using the enrollment token and Cloudflare/service-token path where required.
7. User logs in through Firebase or Cloudflare Access.
8. User creates an OCM machine.
9. OCM places the machine on the registered KVM host and provisions per-machine routing/tunnel metadata.
10. User accesses terminal/gateway/SSH through the configured data-plane domain.

Deployment prerequisites to document

• Operator-controlled domain or delegated subdomain on Cloudflare.
• Cloudflare account ID, zone ID, and API token with DNS, Tunnel, Worker, and KV permissions.
• Cloudflare Worker deployed for account/machine route authorization.
• Cloudflare KV namespace for account and route cache.
• Cloudflare Tunnel for the control plane.
• Wildcard DNS/routing for account and machine hostnames.
• Auth provider:
  • Firebase: project ID, web app config, authorized domain, frontend config.
  • Cloudflare Access: team domain, AUD tag, optional service token.
• OCM secrets/config: JWT_SECRET, SECRET_ENCRYPTION_KEY, COOKIE_DOMAIN, DATA_PLANE_DOMAIN, CONTROL_PLANE_URL, OCM_ADMIN_EMAILS.
• KVM host with Firecracker support, cloudflared, bridge/tap networking, rootfs/kernel/runtime assets, and outbound access to Cloudflare/control plane.

Implementation gaps identified

• openclawmachines.com is still hard-coded in backend routing, cookies, enrollment, frontend helpers, Worker host routing/CORS/CSP, and some direct machine URLs.
• Admin/superuser access is currently hard-coded to one email instead of bootstrap configuration.
• ocm_token cookie domain is hard-coded and must be operator-configurable.
• Worker BASE_DOMAIN, routes, host map, and KV bindings need self-hosted configuration guidance or templates.
• Host enrollment is not fully tunnel-first/service-token-aware.
• Firebase is intentionally supported and should remain first-class; emulator support needs an explicit path because emulator ID tokens are unsigned.
• Direct m-*/ssh-* hostnames need a clear protection model: Cloudflare Access, OCM machine token, or account-subdomain Worker route only.

LLM operator runbook

Create a copy-pasteable llms/self-hosted-setup.txt or equivalent that a user can give to Codex/Claude. It should be phase-gated:

1. Inspect repository and existing deployment state.
2. Collect required operator inputs.
3. Validate Cloudflare and auth prerequisites.
4. Generate env/config plan.
5. Deploy/configure Worker/Tunnel/control plane with explicit confirmation.
6. Register KVM host.
7. Run smoke tests.
8. Report resource IDs, URLs, unresolved gaps, and next commands without printing secrets.

Acceptance criteria

• A public doc explains self-hosted prerequisites, architecture, config, setup order, and validation flow.
• A copy-pasteable LLM operator runbook exists and forbids architecture drift.
• The docs make clear that self-hosted OCM keeps the hosted Cloudflare/Firebase/Worker/KVM architecture.
• Required env vars and Cloudflare/Firebase setup are listed before deployment steps.
• The issue links to follow-up implementation work for domain/config portability if not completed in the same PR.

[mathaix]

Opened PR #8 from branch docs/self-hosted-control-plane-runbook.

This first slice documents the self-hosted prerequisites, adds a redacted operator env template, and adds llms/self-hosted-setup.txt as the copy-pasteable Codex/Claude operator runbook. The issue remains open for the follow-up portability work called out in the new doc: configurable domain/cookie/admin bootstrap, Worker templates, tunnel-first host enrollment, Firebase emulator support, and direct m-*/ssh-* protection policy.

[mathaix]

Progress update:

• Opened PR fix: make self-hosted domains configurable #9: fix: make self-hosted domains configurable #9
• Implemented configurable backend COOKIE_DOMAIN and frontend VITE_COOKIE_DOMAIN logout cleanup.
• Moved tunnel reaper orphan DNS cleanup to configured OCM_DATA_PLANE_DOMAIN / DATA_PLANE_DOMAIN.
• Moved Worker account extraction, CORS, Hermes dashboard parent-origin allowlist, and CSP frame ancestors to configured BASE_DOMAIN.
• Updated self-hosted docs/env template to remove stale already-fixed gaps and list the actual operator env values.

Validation completed:

• make check
• go test ./internal/tunnel ./internal/config ./internal/api
• go test -short ./...
• npm run typecheck in frontend
• npm run test in frontend
• timeout --kill-after=10s 120s npm run test in worker
• make test

Remaining issue #7 work after PR #9:

• Provide operator-specific Worker route and KV templates.
• Make host enrollment tunnel-first and service-token-aware.
• Add Firebase Auth emulator support for integration tests.
• Define and enforce the direct m-* and ssh-* hostname protection policy.
• Continue auditing hosted-domain examples/test fixtures as runtime paths move to operator config.

[mathaix]

Hosted-domain audit pass complete (the last remaining-work bullet). Runtime paths are now clean:

• frontend/vite.config.ts sitemap hostname — was the last true hardcode in a runtime build path; now VITE_SITE_URL-configurable (merged in frontend: sitemap hostname configurable via VITE_SITE_URL (issue #7 audit) #32).
• worker/worker.js DEFAULT_BASE_DOMAIN — deliberate env-overridable fallback (BASE_DOMAIN) from fix: make self-hosted domains configurable #9; left as designed.
• Everything else matching openclawmachines.com in backend/frontend/worker/scripts is comments, examples, or test fixtures with env overrides.

Still open from the remaining-work list: operator Worker route/KV templates; tunnel-first + service-token-aware enrollment; Firebase Auth emulator for integration tests; the direct m-*/ssh-* hostname protection policy.

🤖 Generated with Claude Code