Control-Plane SDK Quickstart

Enroll a connected runtime, understand the bootstrap command, and meet the v1 contract.

Requirements#

runtime version 3.4.0 or later
3.6.0 or later for the full sync contract
a workspace API key generated from LumenFlow Cloud

Connected-runtime lifecycle#

The full lifecycle of a connected runtime on the control plane:

  Operator creates workspace
      |
      v
  Enroll ──> POST /enrollments
      |       returns: credential + connect command + SDK descriptor
      v
  Bootstrap ──> npx lumenflow cloud connect ...
      |          writes control_plane: block to workspace.yaml
      v
  Register ──> POST /sessions
      |          agent appears in fleet inventory
      v
  Heartbeat loop (every 30s)
      |   POST /heartbeat ──> returns: dispatch assignment, budget, signals
      |       |
      |       v
      |   Pull desired state: GET /config, GET /policies
      |       |
      |       v
      |   Execute work (claim WU from dispatch queue)
      |       |
      |       v
      |   Push observed state: POST /events, /evidence, /telemetry
      |       |
      |       v
      |   Complete: POST /delivery/wus/{wuId}/complete
      |       (unblocks dependent WUs, may complete initiative)
      |       |
      v       v
  Dashboard shows: fleet health, delivery progress, operator controls

Enroll a runtime#

Create a workspace or regenerate its API key
Copy the generated connectCommand or sdkEnrollment descriptor
Set the workspace token in LUMENFLOW_CLOUD_TOKEN
Run the bootstrap command in the runtime you want LumenFlow Cloud to govern

Example:

export LUMENFLOW_CLOUD_TOKEN=lf_your_workspace_token
npx lumenflow cloud connect --endpoint https://lumenflow.cloud --org-id <org-id> --project-id <workspace-id> --token-env LUMENFLOW_CLOUD_TOKEN

What the SDK descriptor contains#

Field group	Purpose
bootstrap	Connect command, endpoint, org ID, workspace ID, and token environment
desiredState	Canonical config and policy fetch paths
observedState	Sessions, heartbeat, events, evidence, and telemetry paths
compatibility	Minimum supported runtime version and full-sync version

Governance posture#

Connected runtimes inherit the same workspace-level controls as hosted Sidekick. Budgets, approvals, and enterprise governance stay in the hosted control plane. A runtime may run in your environment, but it does not become a separate authority plane.

Operational guidance#

treat the workspace token like any other production secret
keep the runtime on 3.6.0+ if you want the full sync contract
watch Observe for runtime health, compatibility, and drift visibility
rotate the API key if the runtime token is exposed or the environment changes