Control-Plane SDK Quickstart

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

Requirements#

runtime version 5.0.0 or later
6.0.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
  Liveness loop (every 30s)
      |   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

Agent Passport release compatibility#

Agent Passport v1 has a Cloud-owned contract descriptor, but it is currently deferred: it is not yet an active public endpoint or a generally available SDK capability. Do not integrate against an assumed Passport route yet.

Cloud activates Agent Passport only for a verified release whose compatibility manifest explicitly declares agent_passport.v1. The accompanying release evidence index must validate and contain matching evidence for that manifest digest. This prevents a package install, a floating tag, or an unpublished contract draft from being mistaken for supported production behavior.

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 6.0.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