MANUAL · DOCUMENTATION

Governed runtime and control plane
for AI work.

Start with the runtime, then follow the guides for software delivery, Sidekick, or connected runtimes. Policy, approvals, and evidence stay consistent across every surface.

Choose your path

All topics

Build with LumenFlow

Connect your own agents and tools to the control plane — SDK enrollment, MCP servers, and the full API.

Developer Guide

Control-plane SDK, governed runtimes, and API access for programmatic integration.

API & SDK Access

Programmatic access for connected runtimes, workspace exports, and governed automation flows.

Governed Runtimes Overview

How connected runtimes enroll through LumenFlow Cloud and stay governed centrally.

Control-Plane SDK Quickstart

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

Delivery Orchestration

Manage software delivery initiatives, work units, dispatch lanes, and operator actions through the hosted delivery API.

Runtime Sessions

Inspect hosted runtime workflows, turns, continuations, and operator actions for governed agent execution.

DORA Metrics

Track deployment frequency, lead time, change failure rate, and mean time to recovery for AI software delivery.

Traces and Evidence Chains

Browse task execution traces, span-level detail, and evidence receipt chains for auditability.

Memory Sync

Share project state across agents with version-based conflict resolution.

Observe Dashboard

Cross-workspace governance overview — evidence vault, external agents, fleet health, and rollout posture.

Gates and Policy Enforcement

Monitor gate health, pass rates, policy denials, and compute performance across governed workspaces.

Fleet Management

Monitor connected-runtime inventory, drift detection, policy distribution, and authority modes.

Connected-Runtime Enrollment

Enroll external runtimes via the enrollment API, manage credentials, and monitor health.

Connections: Trusted Compute

Run AI work on your own trusted compute under LumenFlow's governed runtime, with policy, approvals, and proof.

Connected Compute

Route governed work to customer-owned machines or LumenFlow-managed runners with one policy, lease, evidence, routing, and metering model.

Desktop and mobile surfaces

What shipped for Tauri desktop and Expo mobile, what each surface is for, and which release-readiness items remain explicit.

Connected Runtime Reference Bridge

Connect a trusted external runtime to LumenFlow so sessions, governed tool calls, and evidence receipts stay inside the canonical control plane.

Enterprise Trust

Org-scoped trust dashboard, enterprise auth configuration, and governance readiness posture.

Evidence Vault

Durable evidence custody, retrieval, and compliance export for governed agent actions.

Approval Workflows

Budget, autonomy, and operator-control approvals with discussion threads and transition history.

Connect a project to LumenFlow Cloud + consume the API

End-to-end walkthrough: create a workspace, issue an API key, run npx lumenflow cloud connect from your project, then call the Sidekick API for actions and the engagement-projection API for read-only cross-project consumption.

Organization-wide observability

Organizations running many LumenFlow workspaces can use a single org-scoped token for a cross-workspace view of active work, dispatch, agent activity, cost, and DORA metrics — with role-scoped views for executives, delivery leads, and engineers.

Bring your own compute (BYOC)

Run governed work on your own machines. LumenFlow's cloud issues a scoped authorization envelope — permissions, budget, a kill switch, and a confinement posture — to a local runner, then ingests per-action evidence and cost back. Your compute, LumenFlow's governance.

Federation: governed agents on your own network

Run LumenFlow's governed agents inside your own private network, connected back to the cloud control plane. Federation keeps execution and data on your side of the boundary while policy, approvals, and evidence stay centrally governed.

The LumenFlow VS Code extension

The LumenFlow VS Code extension brings the governance cockpit into your editor — lanes, gates, work units, approvals, evidence, and cost, all against your live workspace, without leaving your code.

Governed CI/CD pipelines

Run LumenFlow governance inside your CI/CD pipelines. A first-party action lets your GitHub or GitLab workflows run governed checks and sandboxed tasks and emit the same evidence as any other governed work — so the pipeline is part of the audit trail, not a gap in it.

Standards-portable evidence (OpenTelemetry)

LumenFlow's evidence exports in OpenTelemetry's agent-tracing semantic conventions, so the record of what your agents did can be consumed by the observability stack you already run — Datadog, Grafana, and others — without lock-in.

Connect to LumenFlow via MCP

LumenFlow can act as a server for MCP-compatible AI tools, so they can query your workspace as a connected data source, authenticated with a workspace API key. Today this exposes one read-only tool: a list of your workspace's delivery programs.

Connect a Linux machine as a Connected Compute node

Pair your own Linux machine to run governed Sidekick work under your workspace's policy — prerequisites, the current verified setup path, doctor diagnostics, firewall posture, and how to drain, quarantine, or remove the node.

Connect a Windows machine as a Connected Compute node

Pair your own Windows machine to run governed Sidekick work under your workspace's policy — prerequisites, the current verified setup path, doctor diagnostics, firewall posture, and how to drain, quarantine, or remove the node.

Integrations

Connect external services — webhooks, APIs, and custom MCP servers.

Integrations Overview

How LumenFlow connects to external services across Tool Connections, channels, MCP, OAuth, and API keys.

Google Workspace

Connect Gmail, Google Calendar, Google Docs, and Google Sheets to your workspace.

Slack

Connect Slack for governed sends, provider read access, and guided inbound setup.

GitHub

Connect GitHub to summarize repository work, inspect pull requests, and manage issues.

Jira

Connect Jira Cloud to find matching issues, summarize tickets, and update tracked work.

Notion

Connect Notion to find pages, read shared docs, and make bounded note updates.

Zapier

Connect to 5,000+ apps through Zapier's automation platform.

Webhooks

Send and receive webhook events for custom integrations.

Custom MCP Servers

Build and connect custom tools using the Model Context Protocol.

Microsoft Teams

Connect Microsoft Teams to send governed messages and receive inbound chat via Bot Framework.

Discord

Connect Discord to send governed messages and ingest inbound events via a bridge runtime.

Connect a Telegram bot to send governed messages and receive inbound chat via Telegram webhooks.

Twilio SMS

Connect Twilio to send governed SMS messages and receive inbound texts via Twilio webhooks.

Connect WhatsApp Business to send governed messages, manage templates, and receive inbound chat.

Custom Webhooks

Build bidirectional integrations with any system using custom outbound and inbound webhooks.

Public Q&A Widget

The public Q&A widget on lumenflow.cloud answers visitor questions about LumenFlow and Sidekick. The chat is grounded entirely in this docs corpus (the DOCS_ARTICLES registry) plus the tool-connection registry and pricing tiers — adding a docs article automatically extends what the chat can answer. The widget is read-only and rate-limited; it never accesses workspaces, user data, or operator actions.

Client Engagement Chat

Provide a private, token-protected chat portal for individual clients with vector-retrieved context.

Microsoft 365 (Outlook Mail, Outlook Calendar, OneDrive, To Do)

Sidekick connects to the Microsoft 365 stack: Outlook Mail for sending and triaging email, Outlook Calendar for scheduling and conflict-aware booking, OneDrive for document storage and retrieval, and Microsoft To Do for task tracking. Each is a separate governed connector with its own scope and approval rules.

HubSpot

Connect HubSpot to find contacts and companies, summarise deals, log activity, and create or update records. Sidekick respects HubSpot pipeline permissions and routes risky writes through approval before they hit your CRM.

Greenhouse

Connect Greenhouse to triage candidates, summarise interview kit feedback, and update candidate stage. Sidekick reads through governed connector access and pushes write actions through approval to keep hiring decisions auditable.

Yelp

Connect Yelp Fusion to look up business listings, reviews, hours, and category metadata. Read-only; useful for outreach research, local-market context, and customer-support workflows where the customer references a venue.

Linear

Connect Linear to find and read issues, create and update them, comment, and browse projects — issue tracking and planning from inside Sidekick.

Calendly

Connect Calendly to list event types, check availability, list scheduled events, create scheduling links, and cancel events — scheduling from inside Sidekick.

Microsoft Dataverse

Connect Microsoft Dataverse to list and describe tables, query and search records, fetch a record, and create records — work with your Dataverse data from inside Sidekick.

OpenTable

Connect OpenTable to find restaurants, check dining availability, hold a slot, and create reservations through partner booking flows — from inside Sidekick.

Model Configuration

Managed inference, bring-your-own-key, provider routing, and cost tracking.

Model Configuration Overview

Use managed inference by default, or connect your own model keys for advanced control.

Supported Providers

Details on supported LLM providers — OpenAI, Anthropic, Google — and their capabilities.

API Key Management

Add, rotate, and secure your LLM provider API keys in LumenFlow.

Default Model Settings

Configure per-conversation defaults — temperature, token limits, and system prompts — for your workspace. These defaults apply within whichever workspace AI source you've chosen (managed inference or BYOK); they don't change the source itself. See workspace-ai-source for the workspace-level managed-vs-BYOK decision.

Workspace AI source: managed inference vs BYOK

Every workspace has a single AI source that decides who pays for and operates the model that powers Sidekick. New workspaces default to managed inference (LumenFlow runs the model). You can switch to BYOK to point Sidekick at your own provider key. This is workspace-level — it's separate from per-conversation model selection.

Bringing your own model through OpenRouter

Connect an OpenRouter API key as a bring-your-own-model source, discover what's actually available and what it costs directly from OpenRouter's own live catalog, and understand why LumenFlow never promises a specific model stays free.

Govern AI

Set the policy every action runs through, route approvals, and export evidence for compliance.

Governance & Policy

Define what agents can do. Route risky actions through approvals. Export evidence for compliance.

What Are Governance Bridges?

Governance bridges connect your organization's approval culture to AI-driven automation.

Agent Telemetry & Governance Evidence

When you connect a runtime, LumenFlow captures the full activity surface of your agents and records governance evidence — across any client, model, or BYOK setup — so you can see what your agents did and prove it followed policy.

Approval Flows

Design approval workflows — from auto-approve to multi-step escalation chains.

Cost Controls

Set budgets, per-action limits, and spending alerts to prevent runaway costs.

Audit & Compliance

Every AI action is logged with full context — satisfying audit requirements.

Regulated trust posture

What is live in the regulated-industry governance tier, what is in progress, and which procurement and SOC 2 claims are still explicitly planned.

Roles & Permissions

Control who can configure governance rules, manage connections, and access sensitive data.

Custom Policies

Write advanced governance policies with conditions, schedules, and composable rules.

Autonomy policies and tool-call approvals

Autonomy policy decides which actions Sidekick can take on its own and which require human approval. Trust levels (Supervised, Balanced, Autonomous, Custom) are presets over a tool-call gate, a budget gate, and an approval-required tool list. Risky writes always route to the Approvals inbox before Sidekick proceeds.

LumenFlow vs Microsoft Agent 365

How LumenFlow compares to Microsoft Agent 365 for governing AI agent actions. Agent 365 is the right control plane if you live inside the Microsoft estate; LumenFlow is the neutral alternative for everyone else.

LumenFlow vs OpenClaw

How LumenFlow compares to OpenClaw for self-hosted persistent AI runtimes. OpenClaw popularised bring-your-own-compute personal AI; LumenFlow is what that thesis looks like when it's safe to take to a regulated team.

EU AI Act Article 12 readiness

The EU AI Act's record-keeping (Article 12) and human-oversight (Article 14) requirements for Annex III high-risk systems become enforceable on August 2, 2026. This article maps each requirement to a LumenFlow primitive so a regulated buyer can answer compliance questions concretely.

Governed AI compute: campuses and data centres

Building, running, or managing a data centre, data center, or GPU cluster for AI? LumenFlow is not a facility-management (DCIM) system — it never runs power, cooling, or hardware. What it does is govern and prove the AI compute on the floor: a sealed, independently re-verifiable proof bundle per tenant (utilisation and cost, data residency, carbon, SLA) plus energy and power monitoring.

Energy and carbon provenance

LumenFlow monitors the electricity behind your AI work: it ingests facility power and carbon-intensity signals and PUE, attributes power draw and energy down to the individual compute run and token, and reports every figure with how it was derived — measured, modelled, or estimated — so reporting rests on provenance, not a single blended guess.

Coordination inbox

The coordination inbox is where decision cases land when automated actions conflict or a rule decides a person should weigh in — see what's waiting, who's been asked, and acknowledge each one.

Shadow-agent inventory

A bounded inventory of agent-like activity LumenFlow can observe — its own governed runtimes, agents that describe themselves, and telemetry you send it. Confirm-only: acknowledge or set aside what you see; it never acts on its own.

Security

Encryption, access control, compliance, and data privacy.

Security Overview

How LumenFlow protects your data — encryption, access control, and privacy — and how to report a security issue to security@lumenflow.cloud.

Encryption

How LumenFlow protects your data at rest and in transit.

Access Control

Workspace isolation, role-based access, and session management.

Compliance & Privacy

GDPR, SOC 2 readiness, and data privacy — how LumenFlow handles your data responsibly.

Independently verifiable evidence

LumenFlow seals each evidence anchor and has it independently timestamped by a trusted third-party authority using the RFC 3161 standard — so an auditor can confirm the evidence existed, unaltered, at a point in time without having to trust LumenFlow.

Compliance export

Export what your compliance selection promises and the signed evidence behind it — a workspace-level promise summary, plus an org-level signed audit-export download.

Which credential is for what

LumenFlow uses several distinct, narrowly-scoped credentials instead of one all-purpose secret — a signed-in session, a workspace-wide API key for CI, a single-use code for pairing your own machine, and a durable identity for that paired machine. This is the map of who holds each one, how long it lasts, and what it can and can't do.

Use LumenFlow

Chat with Sidekick, manage your workspace, connect tools, and track billing.

Getting Started

Understand the control plane, set up your workspace, and run your first governed workflow.

What is LumenFlow?

LumenFlow is the governed agent runtime and control plane for AI work. Agents on LumenFlow take real actions — write code, run tests, send email, manage calendars, run workflows — under policy, approval, and evidence rules you control. The kernel, packs, and runtime are proprietary Hellmai Ltd software under the LumenFlow Proprietary License.

Architecture Overview

How LumenFlow's kernel, cloud, and governed surfaces fit together to enforce policy and produce evidence.

Installation & Setup

Create your account, launch a workspace, and configure inference for governed AI workflows.

Your First Workflow

Walk through a complete governed workflow — delegate, approve, execute, and audit.

Next Steps

Where to go from here — set up governance policies, explore the control-plane SDK, or try Sidekick.

Playground and demo workspaces

Three ways to try Sidekick: the public playground (signed-out, fixed scenarios), a demo workspace (signed-in, sample data, throwaway), and a real workspace (your data, your governance). Demo and real workspaces share the same Sidekick — the demo just isolates seeded scenarios so you can experiment without touching real systems.

LumenFlow on mobile (iOS and Android)

LumenFlow has iOS and Android apps that carry the same governed workflows as the web dashboard — you can initiate, review, approve, and resolve governed work from your phone, not just watch it.

LumenFlow Desktop

LumenFlow Desktop is a beta desktop shell around your workspace, currently Linux only — a global command launcher, system tray, native notifications, and deep links, not just a browser shortcut.

Sidekick

A governed AI assistant that operates under your workspace policies.

Building software with Sidekick

Software delivery is one of the Jobs Sidekick handles. In this scenario it claims work units, writes code in an isolated worktree, runs tests, and opens pull requests — all under your policy and approval rules. It works with your code host and deployment tools rather than replacing them.

Sidekick Overview

Sidekick is LumenFlow's governed AI agent. It takes actions on your behalf across software delivery, communication, scheduling, data, and workflows — every action passes through policy and approval gates.

Chat Interface

Navigate Sidekick's chat UI — threads, attachments, keyboard shortcuts, and more.

Delegating Tasks

Prompt patterns, multi-step tasks, and best practices for effective delegation.

Connections

Connect Gmail, Outlook, Greenhouse, Slack, and custom tools to expand what Sidekick can do.

Memory & Context

How Sidekick maintains context across conversations and learns your preferences.

Approvals & Governance

Configure what Sidekick can do automatically and what needs your approval.

Workflows

Build multi-step automations with conditional logic and approval gates.

Billing & Costs

Understand LumenFlow's pricing, token metering, and cost controls.

Routines

Schedule recurring automations, link them to objectives, configure reactive routing, and control trust with autonomy policies.

Briefings

Receive scheduled email digests summarizing routine outcomes, objective progress, and delegated work status.

Notifications

One bilateral inbox for what Sidekick needs from you and what it just did for you — with per-type preferences and multi-transport delivery.

MCP Servers

Tools

Browse available tool connections, test capabilities, manage MCP servers, and control which tools Sidekick is allowed to use.

Onboarding

Onboarding is conversational: a new workspace opens straight into chat, and Sidekick asks for whatever it needs — a model source, a connector — as your first request requires it.

Settings

Manage billing, BYOK and managed-inference model configuration, spending budgets, trust levels, destination defaults, and team permissions from the workspace Settings surface. Owners and admins see the full surface; members see a personal preferences view.

Troubleshooting

Common issues, error messages, and how to resolve them.

Outputs, artifacts, and destinations

How LumenFlow saves generated work from Sidekick, external agents, and fleet workers; what managed artifact links mean; and the two ways a page or app goes public — a hosted app page LumenFlow publishes directly, or a connected deployment destination for a full app — always with your explicit confirmation.

How LumenFlow looks: jobs, agents, and proof

Sidekick is the front door. You ask, LumenFlow plans, agents work, you approve, and proof is kept. This explains the consumer model — jobs, steps, agents, connections, rules, approvals, outputs, and proof — and why visual structure lives inside Sidekick rather than on a separate canvas.

Managed storage and managed runtime

Sidekick ships with built-in defaults for storage and execution: managed artifacts holds generated docs, files, and export bundles in LumenFlow-managed storage, and managed runtime runs builder work when no external execution target is connected. You do not need external artifact storage before Sidekick can save internal outputs; public hosting and deployment still require a connected destination and explicit confirmation.

Builder destinations and publication workflow

Sidekick chooses a destination for every build it does — code, docs, files, runtime, deployment — based on what your workspace has pinned. Managed defaults work without setup; pinned connectors route work to your owned tools (GitHub for code, Notion for docs, OneDrive for files, GitHub Pages or Vercel for deployments). Risky publication steps go through approval before Sidekick proceeds.

Landing preference: Dashboard vs Sidekick

Each user can choose where a workspace opens for them — Dashboard (the workspace overview) or Sidekick (the conversation). The preference is per user and per workspace, doesn't change role authority, and doesn't affect teammates. Switch it any time in Settings.

Governed Sidekick execution

How long-running Sidekick work, parallel subagent fanout, governed browser actions, drift evidence, and routine studio fit inside one evidence boundary.

Autonomous delivery: from one instruction to finished work

Sidekick can take a single instruction and carry it through to finished work — not just answer. Larger asks can branch into several linked pieces of work, with bounded parallel Agents on the independent ones. Autonomous delivery is opt-in per workspace, asks before it starts, streams evidence as it goes, and fails loudly rather than silently.

Hosted app pages: publish a page Sidekick built

When Sidekick builds you a simple, self-contained page — a demo, prototype, or small utility — you can ask it to publish that page directly and get a real, shareable link. Publishing always asks for your explicit confirmation first, every page is checked before it goes live, and you can unpublish it any time. Bigger apps with a backend route to a connected deployment destination instead.

Dashboard Guide

Workspace management, activity feeds, analytics, and team coordination.

Dashboard Overview

The LumenFlow dashboard is your command center across workspaces. Authenticated users land in Sidekick — the conversation surface where you ask, approve, and review work. Jobs gives a non-conversational workspace overview; Settings holds configuration; Agents is the operator depth surface for the swarm runtime.

Workspace Management

Create, configure, and switch between workspaces for different teams and projects.

Activity feed and proof

Monitor real-time activity — actions taken, proposals pending, and governance events. The standalone activity bucket folds into Sidekick's Proof widget and Notifications; per-job activity remains a drill-down inside Jobs.

Analytics & Reporting

Track token usage, action volume, approval rates, and cost trends over time.

Team Members

Invite team members, assign roles, and manage workspace access.

Workspace Settings

Configure workspace defaults, timezone, language, and general preferences.

Notifications

Configure alerts for proposals, budget thresholds, and team activity.

Search

Find conversations, actions, and audit entries across your workspace.

Keyboard Shortcuts

Navigate the dashboard faster with keyboard shortcuts and command palette.

Delivery Dashboard

Track initiatives, work unit progress, and lane dispatch from the delivery dashboard.

Runtime Dashboard

Inspect governed agent sessions, workflow state, and operator controls from the runtime dashboard.

Pipeline Metrics

View script execution telemetry, step breakdown, and lane utilization from the pipeline dashboard.

DORA Metrics Dashboard

Track software delivery performance with deployment frequency, lead time, change failure rate, and MTTR.

Evidence Chain Traces

Browse task execution traces, bridge detection, and span-level audit detail.

Agents: operator surface for agents and swarm

Agents is the operator depth surface. Today it shows the job graph, action rail, output explorer, and live runtime overlay; its direction is to become the Agents/Operations view for roster, coordinator decisions, handoffs, escalations, leases, and stuck states. Consumers stay in Sidekick.

Replay: governed replay chain

Replay is the workspace-level surface at /dashboard/<workspaceId>/replay that shows the latest governed replay chain — the full evidence trail correlating a builder job with its delivery, runtime, and evidence outputs. Use Replay to audit what happened after the fact, prove a decision, or reconstruct the chain Sidekick followed.

Objectives

Objectives is the workspace review page for outcomes you've delegated to Sidekick in conversation — priority, status, success criteria, and progress, all created and updated by talking to Sidekick, not by filling in a form.

Billing

Plans, usage tracking, budgets, and cost alerts.

Use Cases

End-to-end walkthroughs for common governed workflows.

Troubleshooting

Common issues, error codes, and how to get help.