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_CLOUD_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_CLOUD_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_CLOUD_TOKEN

For an interactive local check only, use your shell's env-file loader (for example direnv reading a git-ignored .env.local) so the token never appears as a literal argument or a bare export ...=<secret> line you'd otherwise retype into history.

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