Control-Plane SDK Quickstart

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

Warning

This is the advanced, workspace-API-key-backed CLI/CI enrollment path, not the consumer setup journey. If you're pairing your own Linux or Windows machine as a Connected Compute node, use the workspace Compute page instead — it issues a short-lived, single-use pairing code and never asks you to export a long-lived credential. This quickstart is for automating a runtime (a CI job, a self-hosted build agent) that already has a workspace-scoped API key issued for it under Settings → Advanced.

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
Inject the token into LUMENFLOW_CONTROL_PLANE_TOKEN through your CI provider's secrets store (GitHub Actions secrets, a self-hosted agent's credential manager, and so on) — not a literal export on an interactive command line, which lands the token in shell history
Run the bootstrap command in the runtime you want LumenFlow Cloud to govern

Example, as a CI step consuming a provider-managed secret:

# LUMENFLOW_CONTROL_PLANE_TOKEN is injected by the CI provider's secret store —
# never written with a literal export in a script or shell history.
npx lumenflow cloud connect --endpoint https://lumenflow.cloud --org-id <org-id> --project-id <workspace-id> --token-env LUMENFLOW_CONTROL_PLANE_TOKEN

For an interactive local check, read the key into the variable hidden (read -rs on bash/zsh, Read-Host -MaskInput on PowerShell) so it never appears as a literal argument or a bare export ...=<secret> line in history. The CLI then stores it per project in $LUMENFLOW_HOME/secrets/<workspace-id>.env.

A machine connected this way can report in straight away, but it cannot run work until a workspace owner or admin approves its capabilities on the Compute page. Until then, every request to claim work is refused. The capabilities the machine asks for show up there for you to review, and once you approve them it can run only that approved set. The workspace key cannot approve them itself.

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: hold it only in a CI/CD secrets store or a git-ignored local env file, never in a repository, workspace.yaml, or shell history
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; the previous key is invalidated within ~15 seconds on every cloud instance

This workspace API key is an explicit advanced machine-to-machine credential — not a step in the consumer setup journey. Consumer workspace creation, provider connections, model BYOK, and Linux/Windows Connected Compute pairing each use their own least-privilege identity instead of this key, and none of those flows can be satisfied by pasting this token in.