# LumenFlow full documentation > Public product documentation from the docs registry. Byte budget: 1 MiB (1048576 UTF-8 bytes), including this header and any truncation notice. Complete index: [llms.txt](https://lumenflow.cloud/llms.txt). ## What is LumenFlow? Category: Getting Started URL: https://lumenflow.cloud/docs/what-is-lumenflow ## The governed agent runtime and control plane for AI work AI agents are powerful — but deploying them into real workflows without guardrails is a liability. When an agent modifies data, commits code, sends a message, or triggers a workflow, you need to know **what happened, who approved it, and whether it followed policy**. LumenFlow is the **governed agent runtime and control plane** that sits between AI agents and the actions they take. Teams often start with software delivery because it is the clearest enterprise wedge, but the same runtime also powers Sidekick and connected agents in other workflow domains. It enforces policy, routes risky work through approvals, and keeps an exportable evidence trail of everything. ## Product map LumenFlow is **one governed platform** built around three jobs — **Govern**, **Run**, and **Prove**: | | What it does | Who it serves | |---|---|---| | **Govern** | Set policy, route approvals, and cap budgets before any action runs | Platform teams, compliance | | **Run** | Execute agent work under that policy — chat, workflows, connected runtimes | Everyone on the team | | **Prove** | Capture evidence for every action and export it on demand | Compliance, engineering leadership | **Sidekick is the first-party client** — the governed chat assistant most people use to Govern, Run, and Prove day to day. Teams that need deeper integration connect their own agents and runtimes to the same control plane through the SDK, so custom clients get the same policy, evidence, and approval guarantees Sidekick does. ## What users can now do on LumenFlow Cloud Users can now create, launch, supervise, approve, recover, and audit multi-agent work from the cloud. Jobs is the workspace overview surface for launching and supervising governed work, while Agents shows the live job graph, safe actions, approvals, artifacts, and replay evidence. In practical terms, teams can: - launch governed Sidekick or agent jobs without spawning a local terminal process for supported flows - approve risky actions from the workspace, mobile surfaces, or connected channel surfaces - inspect who acted, what policy applied, what budget decision fired, and what replay evidence was saved - connect external runtimes so existing agents report heartbeat, events, evidence, and health into the same control plane - rely on durable worker scheduling for routines, hosted runtime launches, and wakeups rather than treating cron as the only progress mechanism The product is still governed by workspace policy and rollout flags. LumenFlow does not grant agents unbounded access to tools or data; every connected action still runs through the configured approval, budget, evidence, and replay boundaries. ## How it works | Layer | What it does | |-------|-------------| | **Policy** | Define rules for what agents can do autonomously vs. what requires review | | **Approvals** | Route risky actions through human or automated approval gates | | **Evidence** | Every action is logged with full context — who, what, when, why | | **Export** | Audit trails are exportable for compliance, review, and incident response | ## Kernel and Cloud LumenFlow ships in two forms: - **Kernel** — the enforcement layer that runs wherever your agents run, embedded in your development workflow. It validates agent actions against policy locally. - **Cloud** — the hosted control plane that adds team visibility, approval routing, evidence storage, and export across your organization. You can start with the kernel alone and add Cloud when you need cross-team governance. ## Licensing LumenFlow is proprietary software licensed by Hellmai Ltd. The licence terms are included with every package and apply from first use. LumenFlow Cloud is a hosted service operated by Hellmai Ltd under the terms at [/terms](/terms). Those terms cover your use of the hosted control plane; the package licence covers the software you install. ## Core principles 1. **Policy before execution** — agents propose, rules decide 2. **Evidence by default** — every action produces a proof trail 3. **Human-in-the-loop where it matters** — escalation for risky work, autonomy for safe work 4. **Open architecture** — bring your own models, tools, and runtimes > **info** > LumenFlow is in beta. We're building in public and shipping fast. > Your feedback shapes the product. ## Next step Head to [Architecture Overview](/docs/architecture-overview) to see how the kernel, cloud, and governed surfaces fit together. --- ## Architecture Overview Category: Getting Started URL: https://lumenflow.cloud/docs/architecture-overview ## How LumenFlow is built LumenFlow uses a layered architecture designed around one goal: **every AI action is governed, evidenced, and auditable**. ## The three layers ### Kernel (enforcement) The enforcement layer that runs wherever your agents run. The kernel validates actions against policy, blocks violations, and produces structured evidence — even offline. - **Policy engine** — evaluates rules before any action executes - **Evidence capture** — records what happened, who approved it, and why - **Local-first** — works without Cloud for single-developer workflows ### Cloud (control plane) The hosted layer that adds team-scale governance: - **Approval routing** — send risky actions to the right reviewer - **Evidence storage** — searchable, exportable audit trail - **Team visibility** — dashboards, analytics, and activity feeds - **Connected runtimes** — enroll governed external runtimes through the control-plane SDK ### Governed surfaces Product surfaces that operate under the governance layer: - **Sidekick** — an AI assistant whose actions are governed by your workspace policies - **Dashboard** — workspace management, activity monitoring, and team coordination - **Inference routing** — managed inference or bring-your-own-key, with cost tracking ## Why this matters This separation means you can **start with the kernel** for local enforcement, **add Cloud** when you need team governance, and **trust the evidence trail** because it's produced at every layer. --- ## Installation & Setup Category: Getting Started URL: https://lumenflow.cloud/docs/installation-setup ## Create your account 1. Visit [lumenflow.cloud](/) and click **Start free** 2. Sign up with your email or Google account 3. Verify your email address Account creation is available when sign-ups are open. If the sign-up page says they are temporarily closed, new accounts cannot be created yet; existing users can still sign in. ## Create a workspace Workspaces are isolated environments for teams or projects. Each workspace has its own: - Sidekick conversations - Approval rules - API keys and connections - Usage metering The first ordinary sign-in provisions a standard workspace when you do not already belong to one. To create another, click **New Workspace** in the dashboard and give it a name. A standard workspace persists real work under your policies. The [playground and demo workspaces](/docs/playground-overview) use sample data and simulated connector actions; choose a standard workspace to evaluate actual execution. ## Start with managed inference Managed inference lets you use Sidekick without a provider API key when it is available and your workspace has sufficient credit. When starter credit is offered, your newly created standard workspace receives a **one-time inference grant**, visible in its credit history. It is not an unlimited allowance or a recurring monthly grant, and it does not fund compute jobs. Starter funding can be disabled; an existing workspace does not receive another grant when you sign in again. 1. Open your standard workspace and launch **Sidekick** 2. Check that inference is available and funded 3. Ask Sidekick to create a small task, then reopen the saved result 4. Review any approval required by your workspace policy before execution 5. Open the associated job activity or **Observe** to inspect available evidence Email and other external actions require your own working connections. When credit or a required connection is unavailable, complete that setup before trying the action. ## Optional: bring your own model key If you need a specific provider, model, or enterprise agreement, you can connect a **bring your own model key** in workspace settings. 1. Go to **Settings → Model Configuration** 2. Select a provider and model 3. Paste your API key 4. Save the configuration for the workspace > **success** > Your API key is encrypted and stored securely. LumenFlow never > sends your key to any service other than the provider you selected. ## Next step With your workspace configured, you're ready to [run your first workflow](/docs/first-workflow). --- ## Your First Workflow Category: Getting Started URL: https://lumenflow.cloud/docs/first-workflow ## What you'll build In a standard workspace with available inference, ask Sidekick to save a small task, reopen the result, and inspect the associated evidence. This uses real workspace state without needing an email connection. For an approval walkthrough, use a workspace whose existing policy requires approval for the selected write. Approval requirements depend on that policy; an ordinary chat response alone is not execution proof. ## Step 1: Open Sidekick Navigate to your workspace and click **Sidekick** in the sidebar. You'll see a chat interface — this is where you delegate tasks. ## Step 2: Delegate a task Type a natural-language instruction: ``` Create a task called "Prepare investor follow-up". Include three steps: confirm the requirements, run the acceptance checks, and share the resulting evidence. Show me the saved task. ``` Sidekick selects the available task tool and follows your workspace policy. Check the saved task or returned task identifier rather than relying only on the assistant saying it finished. ## Step 3: Review and approve If policy requires approval, inspect the pending action and its exact arguments before approving or rejecting it. Approve only the task you intended to create, then wait for its execution result. If the action is permitted automatically, the workflow may complete without this pause. ## Step 4: Check the audit trail Ask Sidekick "show me the proof" (or open a Job and view its Activity tab) to see the audit trail. Each entry shows: | Field | Value | |-------|-------| | Action | The actual task tool invocation | | Status | The recorded terminal outcome | | Initiated by | The recorded actor | | Approval | The applicable policy decision and any approval | | Result | The saved task identifier | | Cost | The metered cost, when available | > **info** > Reopen the saved task to confirm persistence. Evidence describes the > action that actually ran; a proposed action or a simulated connector > result does not establish external execution. ## What's next? You've completed the core workflow. Next, explore [Governance & Policy](/docs/bridges-overview) to define approval rules, or see [Next Steps](/docs/next-steps) for all paths forward. --- ## Next Steps Category: Getting Started URL: https://lumenflow.cloud/docs/next-steps ## You're set up You've created an account, configured a workspace, and run your first workflow. Here's where to go next. ## Set up governance Define what your agents can do and what needs review: - [What Are Governance Bridges?](/docs/bridges-overview) — the policy framework - [Approval Flows](/docs/bridges-approval-flows) — rules, thresholds, escalation - [Cost Controls](/docs/bridges-cost-controls) — budgets, alerts, per-action metering - [Audit & Compliance](/docs/bridges-audit-compliance) — evidence export and retention ## Build with the control-plane SDK For programmatic access and runtime enrollment: - [API & SDK Access](/docs/api-reference) — REST API and SDK reference - [Governed Runtimes](/docs/governed-runtimes-overview) — enroll external runtimes - [Control-Plane SDK Quickstart](/docs/control-plane-sdk-quickstart) — get started in minutes ## Try Sidekick Sidekick is a governed AI assistant that operates under your workspace policies: - [Sidekick Overview](/docs/sidekick-overview) — what it is and how it works - [Delegating Tasks](/docs/delegating-tasks) — prompt patterns that work - [Connections](/docs/connections) — integrate Gmail, Calendar, Slack, and more ## Get help Stuck on something? Check [Troubleshooting](/docs/troubleshooting) for common issues and solutions. > **success** > Tip: bookmark the docs sidebar. It's designed for quick reference > while you work. --- ## Building software with Sidekick Category: Sidekick URL: https://lumenflow.cloud/docs/building-software-with-sidekick ## Sidekick ships features end-to-end This page walks through one of the Jobs Sidekick can handle: software delivery. In this scenario Sidekick **claims work, writes code, runs tests, and opens pull requests**, then waits for the operator approvals you've defined. The same governed Job loop runs for any other source — schedules, connected events, API calls, or delivery handoffs — without a scenario-specific surface. This is the same workflow LumenFlow itself ships through. The codebase you're reading right now is built by Sidekick + governed agents claiming work units, working in isolated worktrees, running gates, and merging via the same policy pipeline. ## What Sidekick does in a software-delivery loop | Step | What Sidekick does | |------|--------------------| | **Plan** | Reads your backlog, picks a work unit (WU), breaks it into a worktree-scoped change | | **Claim** | Locks the WU to its lane, creates an isolated worktree, branches from main | | **Implement** | Writes tests and implementation; iterates until the test suite passes | | **Verify** | Runs your gates — format, lint, typecheck, tests, custom co-change rules | | **Open PR** | Pushes the lane branch and opens a pull request with the change, the evidence trail, and the WU spec | | **Govern** | Risky steps (production deploys, destructive ops, secret access) route to operator approval before Sidekick proceeds | | **Audit** | Every action — file read, file write, tool call, LLM turn — is recorded as evidence and exportable | ## What governs the loop - **Policy boundaries** — Sidekick can only change files inside the scope declared for the job, only call tools you've allowed, and only commit to its own workspace. - **Approval gates** — production deploys, destructive git operations, and access to secrets pause for operator approval before Sidekick proceeds. - **Evidence trail** — every action, decision, and tool call is recorded; exportable as JSON or CSV for SOC 2, ISO 27001, or internal audit. - **Cost attribution** — per-job and per-action LLM cost is tracked with caps; runaway turns are blocked at the budget gate. - **Replay** — every job is reproducible from its evidence chain; you can rerun the same work to check the same outcome. ## How to put Sidekick on your repo 1. **Sign up** at [/auth/sign-up](/auth/sign-up) and create a workspace. 2. **Connect your code host** — GitHub or compatible — under [Connections](/docs/connections). 3. **Define lanes** for the kinds of work you want governed (Framework, Experience, Operations, Content). 4. **Create work units** in your backlog using `pnpm wu:create` or the dashboard. 5. **Delegate** to Sidekick from the Sidekick chat or by claiming a WU directly. 6. **Approve** risky steps when Sidekick pauses; everything else runs autonomously and posts evidence to your dashboard. ## Where this fits in LumenFlow Sidekick is the agent surface. The runtime that governs Sidekick — and any other connected agent — is the **control plane**: it enforces policy, routes approvals, captures evidence, and exports audit trails. See [What is LumenFlow?](/docs/what-is-lumenflow) for the broader picture. ## What Sidekick does not replace Sidekick can prepare software changes, generate files, run tests, open pull requests, and produce governed outputs. It does not become your public web host, browser IDE, code host, or deployment platform. For live websites and applications, Sidekick routes work through the destinations you connect and approve: a code host for source truth, a deployment target for public hosting, or a manual export when you have not connected a destination yet. > **info** > Sidekick uses the LLM provider configured in your workspace. Code > generation runs against your chosen provider (Anthropic, OpenAI, or > bring-your-own-key). Your code never leaves your chosen provider's > infrastructure unless you explicitly route it elsewhere. --- ## Sidekick Overview Category: Sidekick URL: https://lumenflow.cloud/docs/sidekick-overview ## What is Sidekick? Sidekick is LumenFlow's governed AI agent. It lives inside your workspace and **takes actions on your behalf** — writing code, running tests, opening pull requests, sending emails, managing calendars, querying data, and running multi-step workflows. Unlike a generic chatbot, Sidekick is **governed**. Every action passes through LumenFlow's policy and approval pipeline, so you always know what happened, who approved it, and why. ## What Sidekick can do | Capability | Examples | |-----------|---------| | **Software delivery** | Claim a work unit from your backlog, write code in an isolated worktree, run tests, open a pull request — see [Building software with Sidekick](/docs/building-software-with-sidekick) | | **Communication** | Draft and send emails via Gmail or Outlook | | **Scheduling** | Create, modify, and cancel calendar events | | **Data** | Query databases, generate reports, summarize documents | | **Workflows** | Run multi-step automations with approval gates | | **Research** | Search the web, summarize articles, compare options | ## How governance works in Sidekick Every Sidekick turn flows through the same governance pipeline as any other agent on the runtime: ``` Message in | v Budget check ──(over limit)──> turn_blocked | v LLM call ──> cost_event recorded | v Tool dispatch | +──(safe tool)──> Execute ──> Evidence captured | +──(risky tool)──> Approval gate | +──(approved)──> Execute ──> Evidence captured | +──(pending)──> turn_paused, notify operator | v Reply to channel ──> turn_completed ``` Every turn reaches exactly one terminal state: **completed**, **blocked** (budget), or **paused** (approval). If none is reached within the SLA window, a `stall` signal fires. ### Step by step 1. **You delegate** — describe what you want in natural language 2. **Sidekick plans** — breaks the task into steps and proposes actions 3. **Governance applies** — rules determine what's auto-approved vs. needs review 4. **Actions execute** — approved steps run and results appear in chat 5. **Everything is logged** — full audit trail in Observe > **info** > Sidekick uses the LLM provider configured in your workspace. > Your data never leaves your chosen provider's infrastructure. ## Sidekick is a conversation, not a bucket of pages Sidekick is the conversation. Plans, approvals, output previews, proof, and the agents involved render inline as widgets inside the chat — you do not navigate between separate pages to do different parts of the work. Configuration surfaces (connections, rules, notifications, API keys, model defaults, memory preferences) live in **Settings**. Operator depth (the swarm graph, participant roster, coordinator decisions) lives in **Studio**. From Sidekick you ask, you approve, and you get proof — that is the whole product surface. ## Getting started If you haven't already, complete the [Getting Started](/docs/what-is-lumenflow) guide to set up your workspace. Then continue with [Chat Interface](/docs/chat-interface) to learn the UI. --- ## Chat Interface Category: Sidekick URL: https://lumenflow.cloud/docs/chat-interface ## The chat window Sidekick's interface is a persistent chat within your workspace. Messages are organized in a single thread per conversation, with support for multiple conversations. ## Composing messages Type in the input area at the bottom of the screen. Press **Enter** to send, or **Shift+Enter** for a new line. ### Keyboard shortcuts | Shortcut | Action | |----------|--------| | `Enter` | Send message | | `Shift+Enter` | New line | | `Ctrl+K` | New conversation | | `Escape` | Close proposal panel | ## Proposals When Sidekick wants to take an action, it creates a **proposal card** inline in the chat. The card shows: - What the action will do - The data involved (email body, calendar details, etc.) - Approve / Edit / Reject buttons Each proposal includes a unique identifier, the action to be taken, a description, the relevant data, and a status (pending, approved, or rejected). You can review every detail before deciding. ## Conversation history All conversations are saved and searchable. Use the sidebar to switch between conversations or start a new one. > **warning** > Deleting a conversation removes its messages but preserves > audit trail entries in Observe. Actions are never lost. --- ## Delegating Tasks Category: Sidekick URL: https://lumenflow.cloud/docs/delegating-tasks ## Effective delegation Sidekick works best with clear, specific instructions. Think of it like briefing a capable colleague — context helps. ## Prompt patterns ### Be specific ``` ❌ "Handle the meeting" ✅ "Schedule a 30-minute meeting with the design team for Thursday afternoon. Title it 'Q2 Review Follow-up'." ``` ### Provide context ``` ❌ "Send an update" ✅ "Send a Slack message to #engineering summarizing today's deploy: 3 features shipped, 0 incidents, 2 PRs pending review." ``` ### Multi-step tasks You can describe complex workflows in a single message: ``` 1. Pull last week's support tickets from Jira 2. Categorize them by severity (critical, high, medium, low) 3. Draft a summary report 4. Email it to support-leads@company.com ``` Sidekick will create a proposal for each step, executing them in sequence after approval. ## Tips for better results 1. **State the goal**, not just the action — "I need to reschedule because of a conflict" gives more context than "move the meeting" 2. **Mention constraints** — "before Friday", "keep it under 200 words", "use formal tone" 3. **Iterate** — if the first proposal isn't right, reject and rephrase > **info** > Sidekick remembers context within a conversation. You don't need > to repeat background information in follow-up messages. --- ## Connections Category: Sidekick URL: https://lumenflow.cloud/docs/connections ## What are connections? Connections link external services to your workspace, giving Sidekick the ability to take real actions — send emails via Gmail, manage Google Calendar events, and more. ## Available connections | Service | Capabilities | Status | |---------|-------------|--------| | **Gmail** | Read, send, and manage emails | Ready | | **Google Calendar** | Read and create events | Ready | | **Outlook Mail** | Read, send, and manage emails | Ready | | **Outlook Calendar** | Read and create events | Ready | | **Greenhouse** | Read candidates and jobs | Ready | | **Slack** | Governed sends and provider read access | Available today | | **Custom MCP** | Any tool via Model Context Protocol | Ready | > **info** > Slack currently supports governed outbound sends and provider read access. > Automatic inbound chat depends on completing the Slack Events API setup > path for your workspace. ## Setting up a connection 1. Go to **Settings → Connections** in your workspace 2. Click **Add Connection** 3. Select the service and authenticate via OAuth 4. Choose which scopes to grant Once authorized, the connection appears in your settings with its status and granted permissions. ## MCP (Model Context Protocol) For custom integrations, LumenFlow supports MCP servers. You can connect any tool that implements the MCP specification. 1. Deploy your MCP server 2. Add the server URL in **Settings → Connections → Custom MCP** 3. Sidekick discovers available tools automatically > **warning** > Connections grant Sidekick real-world capabilities. Review the scopes > carefully and use governance rules to control which actions are > auto-approved. ## Revoking access To disconnect a service, go to **Settings → Connections**, find the service, and click **Revoke**. This immediately stops Sidekick from using that connection. --- ## Memory & Context Category: Sidekick URL: https://lumenflow.cloud/docs/memory-context ## How memory works Sidekick maintains two types of context: ### Conversation memory Within a single conversation, Sidekick remembers everything discussed. You can reference earlier messages, build on previous proposals, and iterate on drafts without repeating yourself. ### Workspace memory Across conversations, Sidekick learns patterns from your interactions: - **Preferences** — tone, formatting, common recipients - **Corrections** — when you edit proposals, Sidekick adjusts - **Patterns** — recurring tasks and workflows ## Context window Each message to the LLM includes relevant context: your governance rules, workspace preferences, recent conversation history, available tools and scopes, and your current message. This context is assembled automatically — you don't need to manage it. ## Privacy - Memory is **workspace-scoped** — it never leaks between workspaces - You can clear workspace memory in **Settings → Privacy** - Conversation history can be deleted individually - The audit trail in Observe is separate and cannot be deleted > **success** > Sidekick gets better as you use it. Corrections and edits are the > fastest way to teach it your preferences. --- ## Approvals & Governance Category: Sidekick URL: https://lumenflow.cloud/docs/approvals-governance ## The approval model By default, every action Sidekick proposes requires your explicit approval. As you build trust, you can create rules that auto-approve certain actions. ## Governance rules Rules define conditions under which actions are automatically approved. For example, you might auto-approve all calendar reads from Google, while requiring manual approval for email sends. ## Rule types | Type | Description | |------|------------| | **Auto-approve** | Action executes without manual review | | **Require approval** | Action waits for your explicit approval | | **Block** | Action is rejected automatically | | **Escalate** | Action is routed to a specific team member | ## Creating rules 1. Go to **Settings → Governance** in your workspace 2. Click **New Rule** 3. Define the condition (action type, connection, cost threshold) 4. Choose the effect 5. Set priority (higher priority rules override lower ones) ## Cost-based governance You can gate actions on estimated cost: - Auto-approve actions under 1,000 tokens - Require approval for actions between 1,000–10,000 tokens - Block actions over 10,000 tokens > **warning** > Start restrictive and loosen rules as you build confidence. > It's easier to auto-approve more than to undo an action. ## Audit everything Regardless of approval rules, every action — auto-approved or manual — appears in the Observe audit trail with full context. ## Checking what's waiting on you Ask Sidekick directly — "what's waiting on my approval" or "what's pending" — and it lists what needs your decision right now: which action, what it's for, and when it was requested. You don't need to open the approvals surface first to find out. --- ## Workflows Category: Sidekick URL: https://lumenflow.cloud/docs/workflows ## What are workflows? Workflows are multi-step automations that Sidekick executes on your behalf. Each step can use different tools and connections, with governance rules applied at every stage. ## Creating a workflow Describe the workflow in natural language: ``` Every Monday at 9am: 1. Pull the week's support tickets from Jira 2. Categorize by severity 3. Generate a summary report 4. Send to #support-leads in Slack ``` Sidekick will create a workflow definition with approval gates at each step. ## Workflow structure Each workflow has a name, a trigger, and a series of steps. Every step defines an action, which connection it uses, and what approval level is required (auto, manual, or rule-based). ## Triggers | Trigger | Description | |---------|------------| | **Manual** | You start the workflow from the UI or API | | **Scheduled** | Runs on a cron schedule (daily, weekly, etc.) | ## Error handling If a step fails, the workflow pauses and notifies you. You can: - **Retry** the failed step - **Skip** the step and continue - **Abort** the entire workflow > **info** > Workflow executions appear in Observe with per-step detail. > You can trace exactly where something went wrong. --- ## Billing & Costs Category: Sidekick URL: https://lumenflow.cloud/docs/billing-costs ## How billing works LumenFlow meters usage at the workspace level. You pay for: 1. **Plan tier** — Free, Team, or Enterprise 2. **Managed inference** — paid from prepaid credit in your inference wallet, with a starting credit on Free 3. **BYOK provider charges** — only when you choose to route through your own model key ## Viewing costs Go to **Settings → Billing** in your workspace to see: - Current month's token usage - Cost breakdown by action type - Historical trends (daily, weekly, monthly) ## Cost controls Cap Sidekick spend with named, workspace-scoped limits at **Settings → Rules**: a period (daily, weekly, or monthly), a USD limit, and what happens at the limit — warn and keep going, or block until the period resets. Each limit shows a live gauge of spend against its cap. See [Spending Limits](/docs/billing-budgets-alerts) for the full walkthrough. ## Plans | Plan | Price | Includes | |------|-------|----------| | **Free** | $0/mo | 1 workspace, 1,000 events/day, 7-day retention, $1 managed inference credit | | **Team** | $49/mo | Up to 5 workspaces, 50,000 events/day, 90-day retention, metered managed inference | | **Enterprise** | Custom | Unlimited workspaces, unlimited events, 365-day retention, volume pricing, dedicated support | > **info** > Managed inference appears on your LumenFlow bill. If you connect a > bring your own model key, the provider bills that usage directly. --- ## Routines Category: Sidekick URL: https://lumenflow.cloud/docs/sidekick-routines ## Automate recurring operator work Routines are the heartbeat of Sidekick's autonomous capabilities. A routine is a named, repeatable set of instructions that Sidekick executes on a schedule or in response to verified inbound signals. Open **Settings → Routines** to create, edit, and monitor recurring schedules. The autonomy controls (which steps Sidekick may run on its own) live next door at **Settings → Rules**. You can also ask Sidekick to "show me my routines" or "schedule X for tomorrow" — Sidekick edits the same routine state from the conversation. For composing a routine step-by-step without writing code, the **routine studio** (under Sidekick → Studio) gives non-engineers a guided canvas that materializes into the same governed routine store. It surfaces only the connector verbs your workspace can actually use, and attaches the same Rules, approvals, and budget gates as routines created from the conversation. ## Restore a prior version Every version of a Studio routine is kept. To bring one back, call `POST /api/v1/sidekick/studio/routines/{routineId}/versions/{version}/restore` with the version number you want. This never rewrites history — it reads that version's saved content and appends it as a new version on top, so the version you restored from keeps existing exactly as it was. Restoring requires the same permission as publishing a new version, and the restored content is re-validated against your workspace's current connectors and policy before it's saved. If a connector it relied on is gone, or policy would now block it, the restore is refused rather than resurrecting something you could no longer publish today. A successful restore records a receipt naming the version it was restored from. ## Creating a routine 1. Give the routine a descriptive **name** (e.g. "Weekly support digest") 2. Write the **steps** in plain language — Sidekick converts them into a briefing plan that runs through the pipeline 3. Optionally link to an **objective** so the routine's output feeds into a standing goal > **info** > If no routines exist yet, the page offers a one-click path to the > guided onboarding wizard where you can create your first routine > in minutes. ## Schedule-only vs. reactive Every routine starts in **schedule-only** mode. It runs on its configured cron cadence and nothing else. Turn on **reactive routing** to let the routine also fire when a verified inbound message arrives from a connected channel. This is useful for routines that should both run on a schedule and respond to external triggers. | Mode | Trigger | Use case | |------|---------|----------| | **Schedule-only** | Cron expression | Daily stand-up summary, weekly report | | **Reactive** | Inbound signal + schedule | Customer reply triage, alert escalation | ## Autonomy policy The autonomy controls (formerly the Autonomy Policy Editor on the routines page) are now the **Rules** surface at **Settings → Rules**. They control how much freedom Sidekick has when executing routine steps: - **Fail-closed** — if any step encounters a governance violation, the entire run stops immediately - **Approval-required tools** — specific tools that always require human approval before execution - **Blocked tools** — tools the routine may never invoke ## Linking routines to a Job When a routine is linked to a Job, every run automatically updates that Job's progress. This creates a closed loop: the Job defines the goal, the routine does the work, and Sidekick surfaces the outcome inline as Plan/Steps and Proof widgets, with workspace-level progress visible in Jobs. ## The briefing pipeline Under the hood, each routine run executes through the briefing pipeline: 1. Sidekick generates a plan from your step instructions 2. Each step runs against available tools and connections 3. Governance rules and autonomy policy are enforced per step 4. Results are aggregated into a digest 5. The digest is surfaced in Sidekick (as Proof and Outputs widgets) and in Jobs, and can trigger an email briefing > **warning** > Routine runs are subject to your workspace's daily event quota. > If the quota is exceeded, new runs return a 429 until the next day. ## Next step Get scheduled email digests of routine runs in [Briefings](/docs/sidekick-briefings). --- ## Briefings Category: Sidekick URL: https://lumenflow.cloud/docs/sidekick-briefings ## Stay informed without logging in Briefings deliver a formatted email digest to the workspace owner after a routine run completes. They transform raw pipeline output into a scannable summary you can read from your inbox. ## How briefings work 1. A routine runs through the briefing pipeline 2. Step results are aggregated into a digest (tasks, due dates, memories) 3. The digest is formatted as both HTML and plain text 4. An email is sent to the workspace owner's address on file ## Triggering a briefing Briefings are triggered by routine runs. When a routine completes, you can send the results as an email via the briefing email endpoint. There is no separate "briefing schedule" — briefings follow the cadence of the routines they summarize. | Trigger path | What happens | |-------------|--------------| | Routine completes on schedule | Digest is generated and optionally emailed | | Routine completes reactively | Same digest flow, same email delivery | | Manual run via API | POST to the briefings/run or briefings/email endpoint | ## Email delivery Briefings are delivered via Resend. The email includes: - A subject line with the routine name and date - An HTML body with structured sections for each step result - A plain-text fallback for email clients that strip HTML > **info** > Email delivery failures never crash the pipeline. If the email > cannot be sent, the API returns `sent: false` with an error > message, and the digest is still available in the response. ## Quota limits Briefing runs count against your workspace's daily event quota. If the quota is exceeded, the endpoint returns a 429 with a Retry-After header. > **warning** > Make sure the workspace owner has a valid email address in their > profile. If no email is found, the briefing generates the digest > but cannot deliver it. ## Next step Configure where and how you receive alerts with [Notifications](/docs/sidekick-notifications). --- ## Notifications Category: Sidekick URL: https://lumenflow.cloud/docs/sidekick-notifications ## One inbox, both directions The notification feed is a bilateral channel. Sidekick uses it to tell you what it needs (approvals, escalations) and what it just accomplished (routine completions, Job progress). Notification preferences live at **Settings → Notifications**. The feed itself is the in-app notification list (the bell in the workspace nav) and the relevant items also surface inline as Sidekick widgets — for example pending approvals appear as Approvals widgets in chat. ## Notification types | Type | When it fires | |------|--------------| | **Approval required** | Sidekick proposes an action that needs your sign-off | | **Approval resolved** | A pending approval is approved or rejected | | **Agent stalled** | Sidekick cannot make progress and needs operator input | | **Reply received** | An inbound message arrives from a connected channel | | **Routine completed** | A scheduled or reactive routine run finishes successfully | | **Routine failed** | A routine run encounters an error | | **Delegated work attention** | A delegated Job needs operator review | ## Delivery transports Each notification can be delivered through one or more transports: | Transport | Description | |-----------|------------| | **In-app** | Always on — appears in the notification feed inside the dashboard | | **Browser push** | Desktop push notifications via the browser | | **Mobile push** | Push notifications on mobile devices | | **Email** | Delivered to your account email address | | **Channel** | Forwarded to a connected messaging channel (Slack, Discord, etc.) | ## Preferences In **Settings → Notifications**, the preferences panel lets you control delivery per notification type: - **Immediate** — deliver as soon as the event fires - **Muted** — suppress delivery for this type Preferences are workspace-scoped. Changing them in one workspace does not affect other workspaces. > **info** > In-app delivery cannot be muted. Even when other transports are > silenced, the notification always appears in the dashboard feed. ## Deep links Every notification includes a deep link that takes you to the relevant surface — Sidekick (chat with the Approvals or Plan widget pre-rendered), Jobs, or the related Settings section — with the right context pre-loaded. > **warning** > Browser and mobile push require granting notification permissions > in your browser or device settings. If push seems broken, check > your browser's site permissions first. ## Next step Extend Sidekick's capabilities with external tool servers in [MCP Servers](/docs/sidekick-mcp-servers). --- ## MCP Servers Category: Sidekick URL: https://lumenflow.cloud/docs/sidekick-mcp-servers ## Bring any tool to Sidekick MCP (Model Context Protocol) servers let you extend Sidekick with custom tools beyond the built-in integrations. Register a server, and Sidekick automatically discovers the tools it exposes. MCP servers are one connector class folded into Connections. Open **Settings → Connections** and use the MCP server section to manage your server registry. You can also ask Sidekick "what does this need?" and the Connections widget will show you what's wired up and what's missing. ## What is an MCP server? An MCP server is an HTTP endpoint that implements the Model Context Protocol specification. It advertises a list of tools — each with a name, description, and input schema — that an AI agent can invoke. ## Registering a server 1. Open **Settings → Connections** and find the MCP server section 2. Click **Add Server** 3. Provide: | Field | Description | |-------|------------| | **Name** | Human-readable label for the server | | **Slug** | URL-safe identifier (auto-generated from name) | | **Server URL** | The HTTPS endpoint of the MCP server | | **Auth type** | How Sidekick authenticates — bearer token, API key, or none | | **Auth token** | The credential (encrypted at rest, never shown in full) | 4. Toggle **Enabled** to let Sidekick use the server immediately ## Tool discovery Once registered and enabled, Sidekick queries the server for its tool manifest. Discovered tools appear in the [Tools](/docs/sidekick-tools) page, where you can test them and control which ones are available. ## Security - Auth tokens are **encrypted at rest** and never displayed after initial entry - The `hasAuthToken` indicator shows whether a credential is stored - Disabling a server immediately prevents Sidekick from calling its tools > **info** > You can register multiple MCP servers. Tools from all enabled servers > are available in a single unified tool list. > **warning** > MCP servers run outside LumenFlow's infrastructure. Vet the server > before registering it — Sidekick will call any tool the server > advertises, subject to your governance rules. ## Next step Browse and test individual tools in [Tools](/docs/sidekick-tools). --- ## Tools Category: Sidekick URL: https://lumenflow.cloud/docs/sidekick-tools ## See everything Sidekick can do "Tools", "Integrations", "MCP Servers", and "Connections" all fold into one Connections surface — there's no longer a separate Tools page. Open **Settings → Connections** to see every capability available to Sidekick: managed connectors (Slack, GitHub, Google, etc.) and custom MCP server tools combined in one view. From the conversation, ask Sidekick "what's connected?" and the Connections widget will render inline. ## Managed connectors Managed connectors are first-party integrations maintained by LumenFlow. Each connector appears as a card showing: - **Connector name** and icon - **Connection status** — connected, disconnected, or errored - **Account label** — which external account is linked - **Enabled toggle** — turn the connector on or off without disconnecting Click **Connect** on any disconnected connector to start the OAuth flow or credential entry. ## Custom MCP server tools If you have registered MCP servers, their tools appear in the same Connections surface. Each tool shows: - The server it belongs to - Whether the server is enabled - The tool's name and description from the server manifest ## Testing tools Use the test panel to invoke a tool manually and see the raw response. This is useful when: - Setting up a new MCP server and verifying tool discovery - Debugging a routine that calls a specific tool - Checking that credentials and permissions are working ## Governance integration Tools are subject to your workspace's governance rules and autonomy policy. A tool that appears in the browser may still require approval when invoked during a routine, depending on your trust level and per-tool policy. > **info** > The `?connect=` URL parameter on **Settings → Connections** opens with > a specific connector card focused — useful for deep links from onboarding or > other surfaces. > **warning** > Disabling a tool connector does not delete the credential. The > connection remains stored and can be re-enabled instantly. ## Next step Walk through the first-run setup in [Onboarding](/docs/sidekick-onboarding). --- ## Onboarding Category: Sidekick URL: https://lumenflow.cloud/docs/sidekick-onboarding ## One chat, no wizard A new workspace opens directly into chat at `/dashboard/{workspaceId}`. There is no multi-step setup wizard to complete before you can talk to Sidekick — type the first thing you want done, the same way you'd open a conversation with any chat assistant. Onboarding happens implicitly, inline, as part of that conversation. If your request needs something the workspace doesn't have yet — a model source, a connected tool — Sidekick asks for it at the moment it's needed, not as a gate in front of chat. ## What Sidekick asks for, and when | Sidekick needs | What you see | |---|---| | A model source | If neither managed inference nor a BYOK provider key is configured, Sidekick explains what's missing before it can respond, with a link to model configuration | | A tool connection | An inline connect widget appears in the conversation the first time a request needs that integration — for example, asking Sidekick to triage Gmail prompts an inline Gmail connect card | | Workspace or trust decisions | Handled once at workspace creation (the human role and starting trust posture), not repeated as onboarding steps | You never leave the conversation to connect a tool or supply a key — the prompts are inline widgets in the same chat thread. ## Model source Every workspace needs a working model source before Sidekick can respond. Two options: | Model source | What it means | |---|---| | **Managed** | LumenFlow provides the inference endpoint — nothing to configure | | **BYOK** | You supply an API key for your own provider (see [API Key Management](/docs/model-config-api-keys)) | If neither is set, Sidekick's first reply explains exactly what's missing and links to where to fix it, rather than failing silently or showing a generic error. ## Connecting tools inline Tool connections aren't a checklist you work through up front. They surface as inline widgets exactly when a request needs them — ask Sidekick to check your calendar and, if calendar access isn't connected yet, an inline connect card appears in that same message. Approve it once and the request continues. > **info** > Nothing about this flow reads or writes a long-lived workspace credential > into your shell, a repository, or command history. Provider connections use > scoped OAuth installations; model keys are entered once into the encrypted > settings store. See [API Key Management](/docs/model-config-api-keys) for > how those secrets are handled. ## Next step Fine-tune billing, budgets, trust, and model configuration in [Settings](/docs/sidekick-settings). --- ## Settings Category: Sidekick URL: https://lumenflow.cloud/docs/sidekick-settings ## The control center for your workspace The Settings page is where workspace owners and admins configure how Sidekick behaves, what it can spend, and which model it uses. Members see a limited personal view. Open **Settings** from the workspace nav to access the full configuration surface. Every governance and configuration surface — connections, rules, approvals, notifications, API keys, models, routines, memory — lives here, not under a Sidekick sub-route. ## Settings sections The Settings surface is the single home for every governance and configuration concern: | Section | What it controls | |---------|-----------------| | **Workspace** | Workspace name, billing plan, retention, and members | | **Voice** | How Sidekick speaks to you (register, fluency, accessibility) | | **Connections** | Tool connections, MCP servers, integrations, destination defaults | | **Rules** | Autonomy policy — what Sidekick is allowed to do without asking | | **Approvals** | Approval policy — which actions pause for human sign-off | | **Notifications** | Per-type notification preferences and transport choices | | **API keys** | BYOK provider keys (Anthropic, OpenAI, etc.) | | **Models** | Workspace AI source — managed inference or BYOK — and per-role model defaults | | **Routines** | Recurring schedules and one-shot scheduled work | | **Memory** | Per-user memory preferences | ## Trust level presets (Rules) The Rules section exposes trust level presets that wire Sidekick's autonomy gates in one click: | Preset | Behavior | |--------|----------| | **Supervised** | Sidekick asks before every action | | **Balanced** | Handles routine tasks autonomously; asks for sensitive ones | | **Autonomous** | Full autonomy — you review afterwards through Sidekick's Proof widget and Jobs | | **Custom** | You have fine-tuned individual per-tool permissions | Select a preset card to apply it instantly. The autonomy policy editor below the cards shows the granular rules that each preset sets, and lets you override them. ## BYOK and managed inference If you prefer to route inference through your own provider key instead of managed inference: 1. Open **Settings → API keys** and add your provider key (encrypted at rest, shown only as a masked preview) 2. Open **Settings → Models** and switch the workspace AI source to BYOK; pick the provider and model (e.g. `claude-haiku-4-5`, `gpt-4o`) See the full walkthrough in [Workspace AI source: managed inference vs BYOK](/docs/workspace-ai-source). > **info** > Only one active model configuration is allowed per workspace. > Changing the provider replaces the existing key. ## Budget rules Set a monthly spending cap and alert threshold: - **Alert at** — sends a notification when usage reaches this percentage - **Hard stop** — pauses all Sidekick actions until the next cycle Budget enforcement applies to managed inference charges. BYOK usage is billed directly by your provider and not tracked here. ## Role-based access | Role | Settings access | |------|----------------| | **Owner / Admin** | Full access to all sections | | **Member** | Limited personal view — can see AI status but cannot change configuration | | **Viewer** | No access to settings | > **warning** > Changing the trust level to Autonomous removes approval gates > for most actions. Start with Supervised or Balanced until you > are confident in your governance rules. ## Next step If something goes wrong, check [Troubleshooting](/docs/troubleshooting) for common fixes. --- ## API & SDK Access Category: Developer Guide URL: https://lumenflow.cloud/docs/api-reference ## Two public programmatic surfaces LumenFlow exposes two programmatic surfaces today: 1. **Control-plane SDK v1** for connected runtimes that enroll into the hosted control plane 2. **Workspace product routes** for authenticated exports, billing, and dashboard-managed operations ## Authentication ### Connected runtime auth (API key) Connected runtimes authenticate with a workspace API key passed as a `Bearer` token in the `Authorization` header. You receive the plaintext token when you create a workspace or regenerate the key. Routes below marked **API key** use this pattern via `authenticateRequest`. The auth object exposes `workspaceId`, `orgId`, `policyMode`, and `config`. ### Dashboard auth (session cookie) Operator-facing product routes use your authenticated dashboard session cookie. These routes call `authenticateDashboardRequest` and are intended for the hosted product surfaces, not for long-running external runtimes. Routes below marked **Dashboard** use this pattern. ### Enterprise operator auth (dashboard session) Enterprise admin routes authenticate via the dashboard sign-in session and then verify workspace owner/admin access. Routes below marked **Enterprise operator** use this pattern. ### Member auth (user JWT) First-party clients that can't hold a browser cookie — the native and mobile apps — authenticate the workspace **member** with a user JWT passed as a `Bearer` token in the `Authorization` header (never a session cookie). LumenFlow resolves the user, then their workspace membership and access. This is the same person as the dashboard session, just carried as a bearer token instead of a cookie so a native client can call the API directly. Routes below marked **Member (JWT)** use this pattern; it is intended for LumenFlow's own apps, not third-party API integrations (which use the workspace **API key** above). ### Unauthenticated The ops health endpoint requires no authentication. --- ## Endpoint Reference All routes are relative to `/api/v1`. --- ### 1. Sessions Manage agent session registration and fleet topology. #### `POST /sessions` Register or upsert an agent session. - **Auth:** API key - **Request body:** `{ session_id, agent_id, agent_type, wu_id?, lane?, client_type?, agent_version?, host_id?, capabilities?, started_at?, bridge_identity?, governance_context? }` - **Response:** `{ ok: true }` - **Errors:** 400 (missing session_id, agent_id, or agent_type), 500 #### `GET /sessions` List active fleet sessions with topology summary. - **Auth:** API key - **Query params:** `lane?`, `wu_id?`, `include_stale?` (boolean) - **Response:** `{ sessions: FleetSessionReadModel[], topology: FleetTopologySummary }` - **Errors:** 500 #### `DELETE /sessions/:id` Deregister a session by ID. - **Auth:** API key - **Response:** `{ ok: true }` with desired-state contract headers - **Errors:** 500 --- ### 2. Events Governed kernel event ingestion and retrieval (evidence vault boundary). #### `POST /events` Ingest a batch of kernel events. - **Auth:** API key - **Request body:** `{ events: Array<{ kind, task_id?, timestamp, ... } | { eventKind, taskId?, eventTs, payload }> }` - **Max batch size:** 1000 - **Response:** `{ accepted: number }` - **Errors:** 400 (empty batch, batch over 1000 events, telemetry schema failure, operator-control validation), 413 (request body over 1 MiB), 429 (quota exceeded with Retry-After), 500 **Payload limits:** - **Request body:** at most 1 MiB (1,048,576 bytes). The limit is checked on the declared `Content-Length` and again while the body is read. A body over the limit returns 413 with `code: "request_body_too_large"`. - **Telemetry kinds with a fixed schema:** `desktop_shell_panic`, `desktop_boot_connectivity_failure`, `mobile_js_error`, `mobile_error_boundary`, `mobile_forced_non_fatal` and `mobile_storage_encryption_fallback`. Each payload may contain only the fields of its schema. Mobile kinds accept `name`, `message`, `platform` and the optional `stack` and `componentStack`. Desktop kinds accept `message` and the optional `location`. Every text field is capped at 4,000 characters. A payload that fails a check returns 400 with `code: "TELEMETRY_SYNC_DETERMINISTIC"` and an error that starts with "Telemetry payload failed schema validation". Accepted payloads are then passed through the PII redactor. - **Any other kind:** accepted. When the payload is within the cap, it is passed through the PII redactor before storage. - **Unknown-kind payload cap:** 65,536 bytes per event by default. An organization can change it. An event over the cap is still accepted, and its stored payload is replaced by `{ "dropped": "payload_too_large", "bytes": }`. This is not a refusal. #### `GET /events` Query stored kernel events. - **Auth:** API key - **Query params:** `taskId?`, `eventKind?`, `since?` (ISO 8601), `limit?` (1-200, default 50) - **Response:** `{ evidenceVault, filters, events }` - **Errors:** 400 (invalid limit or since), 500 --- ### 3. Evidence Evidence receipt ingestion and retrieval (evidence vault boundary). #### `POST /evidence` Ingest a batch of evidence receipts. - **Auth:** API key - **Request body:** `{ receipts: Array<{ taskId?, receiptType, toolName?, scopeRequested?, scopeAllowed?, scopeEnforced?, inputHash?, outputHash?, payload?, eventTs }> }` - **Max batch size:** 1000 - **Response:** `{ accepted: number }` - **Errors:** 400 (empty/oversized batch, operator-control validation), 429 (quota exceeded), 500 #### `GET /evidence` Query stored evidence receipts. - **Auth:** API key - **Query params:** `taskId?`, `receiptType?`, `since?` (ISO 8601), `limit?` (1-200, default 50) - **Response:** `{ evidenceVault, filters, receipts }` - **Errors:** 400 (invalid limit or since), 500 --- ### 4. Telemetry Runtime telemetry and cost metric ingestion with fan-out to cost tracking. #### `POST /telemetry` Ingest a batch of telemetry metrics. - **Auth:** API key - **Request body:** `{ metrics | records: Array<{ metric, value, tags?, eventTs? | timestamp? }> }` - **Max batch size:** 1000 - **Response:** `{ accepted, costInserted, telemetryInserted }` - **Errors:** 400 (invalid payload or validation errors), 429 (quota exceeded), 500 --- ### 5. Telemetry Pipeline Aggregated pipeline telemetry query. #### `GET /telemetry/pipeline` - **Auth:** API key - **Query params:** `days?` (default 30) - **Response:** pipeline metrics object - **Errors:** 500 --- ### 6. Telemetry DORA DORA (DevOps Research and Assessment) metrics query. #### `GET /telemetry/dora` - **Auth:** API key - **Query params:** `days?` (default 30) - **Response:** DORA metrics object - **Errors:** 500 --- ### 7. Traces Task-level execution trace queries. #### `GET /traces` List execution traces. - **Auth:** API key - **Query params:** `days?` (default 30) - **Response:** `{ traces }` - **Errors:** 500 #### `GET /traces/:taskId` Get detailed trace entries for a single task. - **Auth:** API key - **Query params:** `days?` (default 30) - **Response:** `{ entries }` - **Errors:** 400 (missing taskId), 500 --- ### 8. Memory (Nodes) Project-scoped memory node retrieval. #### `GET /memory/nodes` List all memory nodes for the workspace. - **Auth:** API key - **Response:** `{ nodes }` - **Errors:** none (standard DB errors) --- ### 9. Memory (Sync) Bidirectional memory synchronization with conflict detection. #### `POST /memory/sync` Push and pull memory nodes with version-based conflict resolution. - **Auth:** API key - **Request body:** `{ push_nodes?: Array<{ local_id, lifecycle, version, content_hash, node, updated_at }>, pull_since?: string }` - **Conflict rules:** client version > server = accept; client < server = conflict; equal version + same hash = no-op; equal version + different hash = conflict - **Response:** `{ pushed: { accepted }, pulled, conflicts }` - **Errors:** 400 (non-project lifecycle, invalid push_nodes), 429 (quota exceeded) --- ### 10. Config Workspace configuration with desired-state envelope. #### `GET /config` Retrieve workspace configuration. - **Auth:** API key - **Response:** `{ config, desired_state }` with control-plane SDK headers - **Errors:** none (standard auth errors) --- ### 11. Policies Governance policy retrieval with authority context and desired-state envelope. #### `GET /policies` Retrieve active policies for the workspace. - **Auth:** API key - **Response:** `{ policies, mode, rollout_target, enterprise_governance, desired_state }` with control-plane SDK headers - **Errors:** 500 --- ### 12. Export Compliance export for evidence, events, telemetry, and access reviews. #### `GET /export` Export workspace data for compliance. - **Auth:** API key - **Required query params:** `format` (csv | json), `source` (evidence | events | telemetry | access_review) - **Optional query params:** `since?`, `until?` (ISO 8601). For `access_review`, both `since` and `until` are required plus reviewer signoff params. - **Response (JSON):** `{ complianceExport, data }` with compliance contract headers - **Response (CSV):** file download with `Content-Disposition` header - **Errors:** 400 (invalid format, source, date range, or missing reviewer signoff) --- ### 13. Ops (Health & Status) System health and workspace operational status. #### `GET /ops/health` Unauthenticated database liveness probe. - **Auth:** None - **Response:** `{ ok: true, db: "up", timestamp }` or `{ ok: false, db: "down", timestamp }` (503) #### `GET /ops/status` Workspace operational status summary. - **Auth:** API key - **Response:** operational status object (varies) - **Errors:** standard auth errors --- ### 14. Costs Cost analytics with group-by aggregation. #### `GET /costs` Query cost data with flexible grouping. - **Auth:** API key - **Required query params:** `group_by` (model | agent | wu | session | operation | day), `since` (ISO 8601), `until` (ISO 8601) - **Optional query params:** `wu_id?`, `agent_id?`, `model?`, `session_id?` - **Response:** grouped cost data - **Errors:** 400 (missing/invalid group_by, since, until), 500 --- ### 15. Approvals Operator-control approval workflow with comments and transitions. #### `POST /approvals` Request a new approval. - **Auth:** Dashboard - **Request body:** `{ type, title, description?, requested_by?, metadata? }` - **Response:** `{ approval, enterprise_controls }` - **Errors:** 400 (missing type/title, invalid operator-control payload), 500 #### `GET /approvals` List approvals with optional filters. - **Auth:** Dashboard - **Query params:** `status?` (pending | approved | rejected | expired), `type?` - **Response:** `{ approvals, enterprise_controls }` - **Errors:** 400 (invalid status), 500 #### `GET /approvals/:id` Get approval detail with comments and transition history. - **Auth:** Dashboard - **Response:** `{ approval, comments, transitions, enterprise_controls }` - **Errors:** 404 (not found), 500 #### `POST /approvals/:id` Approve or reject an approval. - **Auth:** Dashboard - **Request body:** `{ action: "approve" | "reject", decided_by?, comment?, reason? }` - **Response:** `{ approval, enterprise_controls }` - **Errors:** 400 (invalid action or transition), 404 (not found), 500 #### `POST /approvals/:id/comments` Add a comment to an approval. - **Auth:** Dashboard - **Request body:** `{ comment, created_by? }` - **Response:** `{ comment }` - **Errors:** 400 (missing comment), 404 (not found), 500 --- ### 16. Enterprise Enterprise SSO/SAML/SCIM configuration and metadata. #### `GET /enterprise` Get enterprise auth configuration and trust surface. - **Auth:** Enterprise operator - **Response:** `{ enterpriseAuth: { orgId, operatorWorkspaceIds, config, contract, readiness } }` - **Errors:** 401 (unauthenticated), 403 (not owner/admin) #### `GET /enterprise/saml/metadata` Download SP SAML metadata XML. - **Auth:** Enterprise operator - **Response:** `application/samlmetadata+xml` - **Errors:** 401, 403, 409 (SAML not configured) --- ### 17. Delivery Delivery initiative management and WU dispatch. #### `POST /delivery/initiatives` Create a delivery initiative graph. - **Auth:** API key - **Request body:** `{ external_id, title, wus: Array<{ wu_id, lane, priority, depends_on[] }> }` - **Response (201):** initiative create result - **Errors:** 400 (missing fields, input validation), 500 #### `GET /delivery/initiatives` List delivery initiatives. - **Auth:** API key - **Query params:** `status?` (active | completed | cancelled) - **Response:** `{ initiatives }` - **Errors:** 400 (invalid status), 500 #### `GET /delivery/initiatives/:id` Get initiative detail. - **Auth:** Dashboard - **Response:** initiative detail object, including `committed_usd`, `envelope_usd`, and `remaining_usd` — spend committed against the initiative's declared budget, the declared cap itself (`null` when no cap was declared), and what remains - **Errors:** 400, 404 (not found), 500 #### `GET /delivery/dispatch` Get delivery dispatch view (queue status and pending assignments). - **Auth:** Dashboard - **Response:** dispatch view object, including an `initiative_budgets` list with the same `committed_usd` / `envelope_usd` / `remaining_usd` figures per initiative that has work in the queue - **Errors:** 500 #### `POST /delivery/dispatch` Apply a WU operator action (release, requeue, or reassign). Requeue and reassign route through the same approval-required governance wrapper as the dashboard operator-action surface, so the response may be a pending approval rather than a direct mutation. - **Auth:** API key - **Request body:** `{ wu_id, action: "release" | "requeue" | "reassign", reason? }` - **Response:** operator action result, or a pending-approval result when the action requires approval - **Errors:** 400 (invalid input), 409 (rejected: not found, conflict, or denied) #### `POST /delivery/wus/:wuId/complete` Mark a delivery WU as complete. - **Auth:** API key - **Request body:** `{ session_id?, completed_at? }` (both optional) - **Response:** WU completion result - **Errors:** 400, 404 (not found), 409 (conflict), 500 --- ### 18. Runtime Hosted runtime session management and operator actions. #### `GET /runtime/sessions` List hosted runtime sessions. - **Auth:** API key - **Response:** `{ sessions }` - **Errors:** 500 #### `GET /runtime/sessions/:id` Get hosted runtime session detail. - **Auth:** API key - **Response:** session detail object - **Errors:** 400, 404 (not found), 500 #### `PUT /runtime/sessions/:id` Upsert hosted runtime workflow state. - **Auth:** API key - **Request body:** full workflow state object with schema_version, session_id, status, timestamps, messages, history, counters, and continuations - **Response:** session detail object - **Errors:** 400 (invalid state), 500 #### `POST /runtime/sessions/:id/actions` Apply a hosted runtime operator action (resume, retry, or abort). - **Auth:** API key - **Request body:** `{ action: "resume" | "retry" | "abort", continuation_messages?, continuation_messages_by_node_id?, reason? }` - **Response:** operator action result - **Errors:** 400, 404 (not found), 409 (state conflict), 500 --- ### 19. Workspace & Org Reads (org-scoped) A second way to read the same kind of data as the sections above: one credential that reads across every workspace in an organization, instead of a key scoped to a single workspace. These are the routes a dashboard, BI tool, or monitoring integration should poll. They follow the read-plane contract below (read budgets, conditional reads, and cursor pagination). #### `GET /workspaces` List every workspace in the caller's organization, with a rollout and agent-fleet summary. - **Auth:** API key (org-scoped token) or Dashboard - **Response:** `{ enterprise_controls, fleet_summary, external_agent_summary, workspaces }` - **Errors:** 401 (unauthenticated), 403 (no organization found), 500 #### `GET /workspaces/:workspaceId/{resource}` One organization credential reads any of a workspace's resources — agents, fleet, sessions, runtime sessions, the dispatch queue, delivery initiatives, the work funnel, coverage, costs, evidence, events, telemetry, traces, approvals, compute sources, coordination state, engagements, health, jobs, lanes, operations, and audit exports — instead of holding a separate key per workspace. - **Auth:** API key (org-scoped token) or Dashboard - **Errors:** 401, 403, 429 (read budget exceeded, see below), 500 #### `GET /orgs/:orgId/fleet-summary` The recommended call for an organization-wide view: one response covering every workspace, instead of calling each workspace's routes in turn. - **Auth:** API key (org-scoped token) or Dashboard - **Response:** a fleet summary spanning every workspace in the organization - **Errors:** 401, 403, 429 (read budget exceeded, see below), 500 Prefer this route over polling each workspace individually when you only need an organization-wide view — see Polling cadence and backoff below. ### 20. App keys and app connectors An app key (`lf_app_`) is the narrow credential a deployed app's server holds. Its scopes, revoke rule and issue rule are in [Credentials and scopes](/docs/credentials-and-scopes). A workspace holds up to a capped number of active app keys. The default cap is five. | Method and path | Purpose | Who may call it | |-----------------|---------|-----------------| | `POST /api/v1/workspaces/{workspaceId}/app-keys` | Mint an app key. The secret is shown once. | An owner or admin dashboard session, or an authorised delegate | | `GET /api/v1/workspaces/{workspaceId}/app-keys` | List the workspace's app keys by display prefix | The same operators | | `DELETE /api/v1/workspaces/{workspaceId}/app-keys/{keyId}` | Revoke an app key. It is refused on its next use. | The same operators | | `GET /api/v1/app-connectors/{appId}` | List an app's connectors. No secret is returned. | A workspace key with `read` | | `PUT /api/v1/app-connectors/{appId}/{connectorKey}` | Store or update a connector. The secret is write-only and encrypted before storage. | A workspace key with `write` | | `DELETE /api/v1/app-connectors/{appId}/{connectorKey}` | Remove a connector | A workspace key with `write` | | `POST /api/v1/app-connectors/invoke` | Invoke an app connector from your server | A workspace key, or an app key holding `app_connectors:invoke` | --- ## Common response headers Most control-plane SDK routes include these headers: | Header | Purpose | |--------|---------| | `Cache-Control` | `no-store` for writes, `private, max-age=30` for reads | | `X-LumenFlow-Authority-Mode` | Current authority mode (authoritative, tighten-only, dev-override) | | `X-LumenFlow-Contract-Version` | Control-plane contract version | | `X-LumenFlow-Runtime-Model` | Runtime governance model identifier | ## Read-plane contract The organization-scoped routes in section 19 above, and the busiest of the per-workspace routes elsewhere in this reference, follow one contract for budgets, freshness, and paging. Build your client against it explicitly — well-behaved polling that ignores this contract is exactly what saturated the service in a past incident, and the limits below are enforced, not just described. ### Read budgets Every organization-scoped token has a daily request budget, checked once per request. The per-workspace routes and the organization summary route (`GET /orgs/:orgId/fleet-summary`) enforce it today. Exceeding it returns: - **Status:** `429` - **Headers:** `Retry-After` (seconds until the budget resets, at UTC midnight) - **Body:** names the limit, the count so far, and the retry delay, for example: ```json { "error": "Daily read limit reached for this token or session. It resets at midnight UTC.", "reasonCode": "read_budget_exceeded", "limit": 50000, "currentCount": 50001, "retryAfterSeconds": 3600 } ``` A per-minute limit, a daily bytes limit, and `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset` headers on every successful and not-modified response are rolling out across the same routes; the daily request budget above is enforced per token today. ### Conditional reads The most frequently polled routes — the workspace collection, the organization summary, and the busiest per-workspace routes — emit an `ETag`. Send it back as `If-None-Match` on your next poll: - Nothing changed: `304 Not Modified`, empty body. - Something changed: a full `200` with a new `ETag`. These same routes are cached for up to 60 seconds, so polling more often than once a minute cannot return anything fresher than a client that waits and sends `If-None-Match`. ### Cursor pagination The list routes — agents, fleet, sessions, runtime sessions, the dispatch queue, and delivery initiatives — accept: - `limit` — page size, default 100, maximum 500 - `cursor` — an opaque token from the previous response's `next_cursor` Pass the previous response's `next_cursor` back as `cursor` to get the next page; a response with no `next_cursor` is the last page. The cursor is opaque — never construct or decode one yourself. A cursor that fails to decode (edited, truncated, or from an incompatible version) returns `400`; start again from the first page rather than retrying the same value. ### Service unavailable When the underlying service is briefly unavailable, a read may return: - **Status:** `503` - **Headers:** `Retry-After` - **Body:** `{ "error": "Service temporarily unavailable", "code": "db_unavailable", "requestId": "..." }` Treat a `503` as transient — wait for `Retry-After`, then retry. This includes spend-gating reads such as `GET /api/v1/costs`: a client that fails closed should do so only after a bounded number of retries that honour `Retry-After`, not on the first `503`. ## Polling cadence and backoff Machine clients must poll politely: - **Poll no more often than every 60 seconds** per resource — responses may be cached for up to that long, so a tighter interval cannot return anything fresher and only adds load. - **Always send `If-None-Match`** with the `ETag` from your previous response, so an unchanged resource costs a cheap `304` instead of a full rebuild. - **Always honour `Retry-After`** on a `429`, `503`, or any other throttled response — it names the earliest useful retry time. - **Back off exponentially with jitter — never at a fixed interval —** when a request fails or is throttled: double the wait on each consecutive failure up to a capped maximum, and add a random fraction of jitter so many clients retrying at once don't synchronize into another burst. - **Prefer the organization summary** (`GET /orgs/:orgId/fleet-summary`) over polling every workspace individually when you only need an organization-wide view. ## Rate limits and quotas Traffic limits vary by plan and workspace. Quota-enforced write routes (events, evidence, telemetry, signals, memory) return `429` with a `Retry-After` header when the daily limit is exceeded; read routes follow the read-plane contract above. Free is intended for evaluation, Team supports sustained operator traffic, and Enterprise is the path for higher-volume governed runtimes or custom throughput needs. ## Next step If you want to connect your own runtime, start with [Governed Runtimes Overview](/docs/governed-runtimes-overview) and then follow the [Control-Plane SDK Quickstart](/docs/control-plane-sdk-quickstart). --- ## Troubleshooting Category: Sidekick URL: https://lumenflow.cloud/docs/troubleshooting ## Common issues ### "Model configuration required" **Cause:** Managed inference is unavailable for the workspace and no bring your own model key is configured. **Fix:** Ask an admin to enable managed access for the workspace or go to **Settings → Model Configuration** and add your own provider key. ### "Connection expired" **Cause:** The OAuth token for a connected service has expired. **Fix:** Go to **Settings → Connections**, find the affected service, and click **Reconnect** to re-authenticate. ### "Action blocked by governance" **Cause:** A governance rule is preventing the action. **Fix:** Review your rules in **Settings → Governance**. Either modify the rule or manually approve the specific action. ### "Budget exceeded" **Cause:** Your workspace has hit its monthly spending limit. **Fix:** Increase the budget in **Settings → Billing** or wait for the next billing cycle. ## Error codes | Code | Meaning | Resolution | |------|---------|-----------| | `E001` | Invalid API key | Check your workspace token | | `E002` | Provider error | Check your LLM provider status | | `E003` | Rate limited | Wait and retry (see Retry-After header) | | `E004` | Governance block | Review governance rules | | `E005` | Connection failed | Reconnect the affected service | | `E006` | Budget exceeded | Increase budget or wait for reset | ## Getting help If you're stuck: 1. Check this troubleshooting guide 2. Search the [docs](/docs) for your specific issue 3. Contact support at **support@lumenflow.cloud** > **success** > Include your workspace ID and the error code when contacting > support — it helps us resolve issues faster. --- ## Governed Runtimes Overview Category: Developer Guide URL: https://lumenflow.cloud/docs/governed-runtimes-overview ## When to use a connected runtime Use hosted Sidekick when you want the fastest path from signup to a working operator. Use a **connected runtime** when you already run your own automation or want LumenFlow Cloud to govern a runtime that lives closer to your systems. ## Hosted Sidekick vs connected runtime | Mode | Best for | Runtime location | |------|----------|------------------| | **Hosted Sidekick** | Non-technical teams and default product onboarding | Managed by LumenFlow | | **Connected runtime** | Technical teams, existing agents, or custom execution environments | Operated by you | ## Shared governance model Both paths use the same hosted control plane for: - approvals and policy decisions - budgets and cost controls - action history and proof trails - enterprise governance overlays such as evidence export and reviewer posture The runtime can execute work in its own environment, but it stays governed centrally by LumenFlow Cloud. ## What ships today - workspace creation and API key regeneration return a ready-to-run connect command - Observe surfaces show runtime inventory, liveness, and compatibility status - connected runtimes report heartbeat, sessions, events, evidence, and telemetry - the current contract supports minimum runtime compatibility from **5.0.0** and full sync from **6.0.0** ## Next step Continue to [Control-Plane SDK Quickstart](/docs/control-plane-sdk-quickstart) for the exact enrollment flow. --- ## Control-Plane SDK Quickstart Category: Developer Guide URL: https://lumenflow.cloud/docs/control-plane-sdk-quickstart > **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 1. Create a workspace or regenerate its API key 2. Copy the generated `connectCommand` or `sdkEnrollment` descriptor 3. 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 4. Run the bootstrap command in the runtime you want LumenFlow Cloud to govern Example, as a CI step consuming a provider-managed secret: ```bash # 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 --project-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 ...=` line in history. The CLI then stores it per project in `$LUMENFLOW_HOME/secrets/.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. --- ## Delivery Orchestration Category: Developer Guide URL: https://lumenflow.cloud/docs/delivery-orchestration ## What delivery orchestration provides LumenFlow Cloud includes a hosted **Software Delivery** pack that tracks initiatives (multi-WU programs), work unit graphs (dependencies and completion), and lane-based dispatch with operator controls. ## Initiatives An initiative groups related work units into a dependency graph with phases. Create one with `POST /api/v1/delivery/initiatives`: | Field | Description | |-------|-------------| | `external_id` | Your identifier for the initiative | | `title` | Human-readable name | | `wus` | Array of work units with `wu_id`, `lane`, `priority`, and `depends_on` | List initiatives with `GET /api/v1/delivery/initiatives?status=active`. Status values: `active`, `completed`, `cancelled`. ## Work unit completion When a work unit finishes, call `POST /api/v1/delivery/wus/{wuId}/complete`. The system evaluates dependency readiness and automatically enqueues newly unblocked work into the dispatch queue. ## Dispatch and operator actions The dispatch board shows ready, claimed, and blocked work units organized by lane. Operators can apply actions via `POST /api/v1/delivery/dispatch`: | Action | Effect | |--------|--------| | **release** | Return a claimed WU to the ready queue | | **requeue** | Move a blocked WU back to ready | | **reassign** | Reassign a claimed WU to a different lane or agent | Sensitive operator actions require approval when configured. ## Next step See the [Runtime Sessions](/docs/runtime-sessions) guide for how delivery work units correlate with agent execution state. --- ## Runtime Sessions Category: Developer Guide URL: https://lumenflow.cloud/docs/runtime-sessions ## What runtime sessions provide The hosted **Agent Runtime** tracks durable execution state for governed agents. Each session has a workflow with turns, continuations, and scheduled wakeups. ## Session lifecycle | Status | Meaning | |--------|---------| | **active** | Currently executing turns | | **waiting_approval** | Paused, awaiting approval decision | | **scheduled** | Sleeping until `next_wake_at` | | **suspended** | Paused, awaiting manual continuation | | **completed** | Finished successfully | | **error** | Terminated with error | List sessions with `GET /api/v1/runtime/sessions`. Fetch detail (workflow state, messages, continuations) with `GET /api/v1/runtime/sessions/{id}`. ## Operator actions Operators can intervene in sessions via `POST /api/v1/runtime/sessions/{id}/actions`: | Action | Effect | |--------|--------| | **resume** | Continue a suspended session with optional messages | | **retry** | Retry a failed session from last checkpoint | | **abort** | Terminate a session immediately | Sensitive actions (abort, retry) require approval when configured. ## Correlation with delivery Runtime sessions correlate to delivery work units via `session_id`. The delivery dispatch board shows workflow status inline for claimed work units, and provides "Inspect runtime" links to session detail. ## Next step See the [DORA Metrics](/docs/dora-metrics) guide for delivery performance measurement. --- ## DORA Metrics Category: Developer Guide URL: https://lumenflow.cloud/docs/dora-metrics ## What DORA metrics measure DORA (DevOps Research and Assessment) metrics quantify software delivery performance. LumenFlow Cloud computes four metrics from telemetry data: | Metric | What it measures | Unit | |--------|-----------------|------| | **Deployment Frequency** | How often you deploy to production | Deploys per day | | **Lead Time for Changes** | Time from commit to production deploy | Hours | | **Change Failure Rate** | Percentage of deploys causing failures | Percentage | | **Mean Time to Recovery** | Time to restore service after failure | Hours | ## Performance tiers Each metric is classified into a tier based on industry benchmarks: | Tier | Badge | Meaning | |------|-------|---------| | **Elite** | Green | Top quartile performance | | **High** | Blue | Above median | | **Medium** | Amber | Median range | | **Low** | Red | Below median | ## API access Query DORA metrics with `GET /api/v1/telemetry/dora?days=30`. Pipeline execution telemetry is available at `GET /api/v1/telemetry/pipeline?days=30`. ## Dashboard Open the workspace overview and select `?panel=dora` to see metric cards with tier badges and trend charts over time. Use the date range picker to adjust the lookback window. ## Getting started Connect your CI/CD pipeline to start tracking. Telemetry events are ingested via `POST /api/v1/telemetry` with the `metric` field set to the relevant DORA metric name. --- ## Traces and Evidence Chains Category: Developer Guide URL: https://lumenflow.cloud/docs/traces-and-evidence ## What traces provide Every governed task execution produces a trace — a directed acyclic graph (DAG) of spans representing tool calls, policy checks, and evidence receipts. Traces are the audit backbone of the control plane. ## Browsing traces List recent traces with `GET /api/v1/traces?days=30`. Each trace has a `taskId` and a timestamp. Fetch span-level detail with `GET /api/v1/traces/{taskId}`. ## Evidence receipts Evidence receipts record what happened during tool execution: | Field | Purpose | |-------|---------| | `scope_requested` | What the agent asked to do | | `scope_allowed` | What policy permitted | | `scope_enforced` | What actually happened | | `io_hash` | Cryptographic hash of input/output for integrity | Receipts are ingested via `POST /api/v1/evidence` and queryable via `GET /api/v1/evidence`. ## Bridge detection Tasks that span multiple systems are flagged as **bridge tasks** in the traces view. Bridge badges indicate cross-system execution chains. ## Dashboard There is no dedicated traces page today. Recent evidence entries appear in the workspace overview's `?panel=evidence` list; the full span-level trace and bridge detail shown here is available through the API only. ## Compliance export Export traces and evidence for compliance with `GET /api/v1/export?format=json` (or `csv`). The export includes evidence receipts, kernel events, and telemetry for the workspace. --- ## Memory Sync Category: Developer Guide URL: https://lumenflow.cloud/docs/signals-and-memory ## Memory sync — shared project state Project memory nodes let agents share state with version-based conflict resolution. ### List nodes `GET /api/v1/memory/nodes` returns all memory nodes for the workspace. ### Sync `POST /api/v1/memory/sync` pushes new nodes and pulls updates since a timestamp. Conflict resolution rules: | Scenario | Outcome | |----------|---------| | Client version > server | Accepted | | Client version < server | Conflict (server wins) | | Same version, same hash | Idempotent | | Same version, different hash | Conflict | Memory is quota-gated per workspace tier. --- ## Observe Dashboard Category: Developer Guide URL: https://lumenflow.cloud/docs/observe-dashboard ## What Observe provides The Observe dashboard at `/dashboard/observe` gives org-scoped visibility across all workspaces you have access to. It surfaces: - **Evidence Vault** — receipt counts, governed tasks, export-ready status - **External Agents** — hosted Sidekick count, connected agents, health - **Runtime Health** — active/inactive/stale runtime counts - **Fleet Rollout** — authority modes, drift status, config revision - **Gate Health** — pass rates, denial trends, compute breakdown - **Policy Denials** — tool-level denial counts - **Scope Violations** — active scope violation count ## Access model Observe shows only workspaces where you have membership. Org membership alone is not sufficient — workspace-level access is enforced. ## Evidence vault section Each workspace shows: - evidence receipt count and governed task count - export-ready or awaiting-evidence status - compliance export source badges and linked export path ## Fleet rollout section Each workspace shows: - distribution mode, config path, policies path - config revision hash - authority badge (Authoritative, Tighten-only, Dev Override) - runtime badge (connected, stale, dormant) - drift badge (aligned, needs reconcile, upgrade required) ## Date filtering Use the date range picker to adjust the lookback window for gate health, policy denials, and compute telemetry. --- ## Gates and Policy Enforcement Category: Developer Guide URL: https://lumenflow.cloud/docs/gates-and-policies ## What gates track Gates are quality checkpoints that governed agents must pass. The gates dashboard shows health, trends, and performance: ## Gate health Open the workspace overview and select `?panel=gates` to see: | Section | What it shows | |---------|---------------| | **Gate Health Table** | Per-gate pass rate with color coding (green >= 95%, amber >= 80%, red < 80%) | | **Activity Trend** | Combined pass + fail counts over time | | **Denial Trend** | Policy denial count over time | | **Task Lifecycle** | Event counts by lifecycle stage (created, scheduled, executed) | ## Gate compute Gate execution performance is tracked as **Gate Compute Time** (not LLM costs — this measures gate execution duration in milliseconds): | Metric | Description | |--------|-------------| | **Total Compute** | Sum of all gate execution time | | **Total Runs** | Number of gate executions | | **Avg Duration** | Average execution time per gate | | **Slowest Gate** | Gate with highest total compute time | ## Policy denials When a governed action violates a policy, the denial is recorded with the tool name and denial count. View denials in the gates dashboard or query via `GET /api/v1/evidence`. ## API access Pipeline telemetry: `GET /api/v1/telemetry/pipeline?days=30` DORA metrics: `GET /api/v1/telemetry/dora?days=30` --- ## Fleet Management Category: Developer Guide URL: https://lumenflow.cloud/docs/fleet-management ## What fleet management provides Fleet management gives operators visibility into all connected runtimes enrolled in a workspace — their health, version compatibility, policy drift, and authority posture. ## Fleet inventory Query fleet state with `GET /api/v1/workspaces/{id}/fleet`. The response includes: | Field | Description | |-------|-------------| | `runtimes` | Array of enrolled runtimes with health, version, and drift status | | `summary` | Aggregate counts (active, stale, dormant, upgrade required) | | `desiredState` | Current workspace config revision and policy mode | ## Drift detection Drift compares desired state (workspace config) against observed state (what each runtime last reported): | Drift Status | Meaning | |-------------|---------| | **aligned** | Config revision matches, version is full-sync compatible | | **needs_reconcile** | Config revision differs — runtime should pull latest | | **upgrade_required** | Runtime version below minimum supported (3.4.0) | | **awaiting_sync** | Enrolled but no heartbeat received yet | > **warning** > Drift detection is v1: it compares against a computed hash of current > workspace config, not a tracked deployment version. Config edits > immediately trigger `needs_reconcile`. ## Policy distribution Connected runtimes pull desired-state configuration from `GET /api/v1/workspaces/{id}/fleet/config`: - `distribution_mode`: always `pull` (runtimes fetch, cloud doesn't push) - `config_path` and `policies_path`: canonical fetch endpoints - `activePolicies`: org-scoped and workspace-scoped policy rules ## Authority modes Each workspace operates in an authority mode: | Mode | Behavior | |------|----------| | **Authoritative** | Cloud config overrides local runtime config | | **Tighten-only** | Cloud can tighten but not loosen local policy | | **Dev Override** | Local runtime config takes precedence (development only) | ## Runtime health Health is derived from heartbeat freshness: | Status | Threshold | |--------|-----------| | **Connected** | Heartbeat < 5 minutes ago | | **Stale** | 5–60 minutes ago | | **Dormant** | > 60 minutes ago | | **Never** | No heartbeat received | ## Dashboard The Observe page at `/dashboard/observe` shows fleet rollout posture across all accessible workspaces with authority, drift, and health badges. --- ## Connected-Runtime Enrollment Category: Developer Guide URL: https://lumenflow.cloud/docs/connected-runtime-enrollment ## What enrollment provides Enrollment registers an external runtime with a workspace so it can participate in the governed control plane — reporting heartbeat, sessions, events, evidence, and telemetry. ## Create an enrollment `POST /api/v1/workspaces/{id}/enrollments` with: | Field | Description | |-------|-------------| | `runtimeName` | Human-readable name for the runtime | | `providerKind` | Runtime provider (e.g., github, gitlab, custom) | The response includes: - `enrollment`: durable record with runtime ID - `runtimeCredential`: plaintext credential (shown once, stored as hash) - `connectCommand`: ready-to-run bootstrap command - `sdkEnrollment`: full SDK descriptor for programmatic setup ## Credential security - Credentials are generated using library crypto (`generateApiKey`) - Only the hash is stored in the database - The plaintext is returned **once** at enrollment time - Rotate by creating a new enrollment if compromised ## List enrollments `GET /api/v1/workspaces/{id}/enrollments` returns all enrolled runtimes for the workspace. Credentials are **not** included in list responses. ## Health monitoring Enrolled runtimes that haven't connected yet appear as "inactive" / "Pending connection" in the external agents inventory. Once they send their first heartbeat, health status transitions to connected/stale/dormant based on heartbeat freshness. ## Access control All enrollment endpoints require workspace membership via `verifyWorkspaceAccess`. Enrollment records are workspace-scoped with RLS policies enforcing isolation. --- ## Connections: Trusted Compute Category: Developer Guide URL: https://lumenflow.cloud/docs/connections-trusted-compute ## Cloud governs. Your compute executes. Proof closes the loop. Trusted Compute is the LumenFlow pattern for routing an **Ask** to an **enrolled connected runtime** running on hardware you control — a developer machine, CI runner, private server, or edge box — and keeping the work governed by policy, approvals, and evidence in Cloud. This is not "LumenFlow runs on anyone's machine." It is **bring your own trusted compute, governed centrally**. ## The chain | Step | What happens | Where it runs | |------|-------------|----------------| | Ask | Operator submits intent | Cloud | | Dispatch | Cloud routes work to an enrolled runtime | Cloud → Runtime | | Rules | Policy decisions allow or deny each scope | Runtime + Cloud | | Tool calls | Runtime executes code edits, tests, etc. | Runtime | | Approvals | Risky actions (e.g. PR creation) pause for human sign-off | Cloud | | Proof | Evidence syncs back, replay assembles the chain | Cloud | ## Evidence bundle Each run writes a canonical evidence bundle. It holds the core Proof files plus a signed manifest: | File | Contents | |------|----------| | `ask.json` | The submitted Ask | | `node-session.json` | Connected-runtime session metadata | | `policy-decisions.jsonl` | Allow / deny decisions per scope | | `tool-calls.jsonl` | Each tool invocation with summaries | | `file-diff.patch` | Code changes produced | | `test-results.json` | Test outcome summary | | `approval.json` | Approval request and resolution record | | `pr-summary.md` | Human-readable PR description | | `replay-link.txt` | URL into Cloud Replay | | `manifest.json` | Schema version, bundle kind, run id, mode, required artifact list, artifact hashes, signer key id, and signature algorithm | | `manifest.sig` | Detached Ed25519 signature over the manifest | | `verifier-public-key.pem` | Public key for independently checking the detached signature | A third party can verify that the required files are present, the hashes match, the schema is supported, and the detached signature validates. ## Naming The user-facing nouns follow the LumenFlow product language: **Ask**, **Connections**, **Rules**, **Approvals**, **Proof**. --- ## Connected Compute Category: Developer Guide URL: https://lumenflow.cloud/docs/connected-compute ## BYOC and managed runners under one governance model Connected Compute is the workspace primitive for running governed agent jobs on either **BYOC** sources you operate or LumenFlow-managed sources. A source can be a laptop, CI runner, Docker host, Kubernetes worker, or the first managed pool. Both paths use the same control-plane contract: | Layer | What is shared | |-------|----------------| | Claim | `POST /api/v1/runtime/claim` assigns eligible runtime work | | Lease | Lease records bound execution and retry state | | Evidence | Receipts, approvals, and replay links stay workspace-scoped | | Routing | Workspace policy chooses `byoc_only`, `byoc_first`, `managed_first`, or `managed_only` | | Budget | Per-job limits refuse before silent fallback | When you post a job, the capabilities you require decide where it can run. A short list of capabilities — including local tool execution, browser actions, local model generation, energy sampling, and MCP tool access — run only on a runner you connect; if no approved runner is online, the job stays queued instead of running somewhere that cannot actually do the work. Jobs that only need LumenFlow-managed capabilities run on the hosted service without any runner connected. Approving a capability for a runner on the compute page covers it regardless of which equivalent name that runner later reports it under — you approve once, not once per runner version. If a runner asks to claim work with a capability you have not yet approved, it shows up on the compute page for you to review and approve, without needing to reconnect the runner. ## What is live - connected-runtime enrollment and health posture - the runtime claim path and assignment lifecycle - compute source read models for operator dashboards - workspace routing policy UI and per-job "assigned to X, why" detail - the first managed-worker registration path - a runner-side compute-class classification (the default is `cpu-small`), recorded on each assignment run ## Current runner setup Open `/dashboard/{workspaceId}/compute` and use **Runner setup**. Enrolling a runner creates a one-time runtime credential and walks through install, enrol, doctor, approve, and start steps for your platform. On Linux, the verified path is the pnpm CLI already in your LumenFlow checkout: `pnpm compute:connect`, `compute:doctor`, `compute:run` and `compute:service`. It needs one prerequisite package — `bubblewrap`, which confines local tool execution — and the same runner directory flows through every step. The start step renders a systemd `--user` unit with `Restart=always`. Once doctor confirms the sandbox is available, the runner requests the `local:tool_exec` and `agent:code` capabilities, which you approve from the same page before the service starts. `compute:service` installs the runner as a systemd service. `install` runs in the systemd user scope by default, and needs `--operator-approved` once the runner's capabilities and posture are approved in the workspace. `status`, `drain` and `uninstall` manage the installed service. Host actuation is Linux only. On macOS and Windows, `compute:service install --dry-run` prints the plan and the other verbs refuse. Windows and macOS use the diagnostic bootstrap below. Local tool execution only ever runs inside a checkout under `~/.lumenflow/workspaces` — the start step creates one there for you (a detached git worktree) and points `--workspace-root` at it. Any other directory is refused, so doctor reporting a workspace-root problem means the fix is a checkout in that directory, not somewhere else on the host. The diagnostic bootstrap commands use Node to fetch the app-hosted bootstrap from `/api/v1/runner/bootstrap`. They do **not** install `@hellmai/lumenflow-cli`, do not require npm registry access, and do not require `LUMENFLOW_CONTROL_PLANE_TOKEN` for doctor or run. The runtime claim made with the one-time credential registers the runner session on the cloud side. Treat the runtime credential as burned if it appears in chat, logs, shell history you do not control, screenshots, or any shared channel. Re-enrol the runner and use the newly shown credential. ## Runner onboarding for agents An agent can bring a runner online under a policy the workspace owner sets. The pieces are separate, and each one is checked on every use. - **Policy.** An owner or admin session sets the policy with `PUT /api/v1/workspaces/{workspaceId}/runner-onboarding/policy`. No key, grant or agent can change it. A change that widens the policy takes effect only after a second, distinct owner or admin confirms it with `POST /api/v1/workspaces/{workspaceId}/runner-onboarding/policy/confirm`. `GET` on the same path shows the policy in force, its expiry, and any widening that is waiting for a second approver. Once the policy expires, no grant can be issued and a held grant is refused. - **Grant.** An owner or admin session, or a key with `runners:manage`, issues a grant with `POST /api/v1/workspaces/{workspaceId}/runner-onboarding/grants`. The grant is an `lf_rog_` credential that carries only `runner:onboard.*` scopes. Its lifetime is 7 to 30 days, 7 by default. A workspace holds a capped number of live grants. Revoke one with `DELETE /api/v1/workspaces/{workspaceId}/runner-onboarding/grants/{grantId}`. A revoked grant is refused on its next use. - **Bootstrap.** The runner's doctor and run steps fetch the runner script from `GET /api/v1/runner/bootstrap`, as described above. - **Capability approval.** The runner's requested capabilities are approved by an owner in the workspace, before the service starts. The credential kinds and their scopes are listed in [Credentials and scopes](/docs/credentials-and-scopes). ## Claim and heartbeat pacing Every claim and heartbeat response tells your runner how soon to check in again. An ordinary response carries a poll-after hint in milliseconds — 30 seconds for claim, 60 seconds for heartbeat by default — so a well-behaved runner never needs a fixed guess. If your workspace's request budget is temporarily used up, the response is a `429` with a `Retry-After` header naming the minimum wait before trying again; if the platform's own admission check is briefly unavailable, you get a `503` with the same kind of `Retry-After` header rather than a silent failure. Both are temporary and independent of your billing or credit balance. The published runner client already honours these headers — you do not need to implement backoff yourself. ## Job results Whichever substrate runs the work — a LumenFlow-managed worker or a connected runner you operate — the result comes back in one shape: the `lumenflow.job_result/v1` envelope. Poll `GET /api/v1/sidekick/jobs/{job_id}` (or watch the SSE stream) until the top-level `status` field reaches `succeeded` or `failed`, then read the envelope from the response's `result_envelope` field (it stays `null` until it is stored). `needs_approval` is a paused state, not a finished one — the job is waiting on a human to approve or reject it, not still running and not done. It is visible on `result_envelope` as soon as it is stored, the same way a finished job's envelope is, but it does **not** fire a push, channel, or webhook delivery the way `succeeded`/`failed` do; keep polling (or watching the SSE stream) past it for the job's eventual `succeeded` or `failed` outcome. | `result_envelope` field | Meaning | |-------|---------| | `status` | `succeeded`, `failed`, `needs_approval`, or `cancelled` (an owner stop) | | `summary` | One paragraph a human can read | | `outputs` | Whatever structured data your job produced | | `artifact_refs` | Links to any files or artifacts the job created | | `evidence_refs` | Links into the workspace's evidence trail for this job | | `correlation` | Echoed back exactly as you sent it, unmodified | | `error` | `null` on success; a reason code and message on failure | The envelope is identical regardless of where the job actually ran, so your integration never needs to know or care which substrate executed it. When LumenFlow's own hosted worker runs the job (rather than a runner you operate), a failed job's `error.reason_code` is one of a small, stable set, so your integration can react without parsing the `summary` text: | `reason_code` | Meaning | |-------|---------| | `model_unavailable` | The workspace has no usable AI model configured for this kind of job | | `model_provider_error` | The configured model's own API call failed — the message names the model and the HTTP status, never the raw response from the model provider | | `managed_artifact_persistence_error` | The job produced its output, but saving it failed | | `runtime_worker_error` | Any other hosted-worker failure | A runner you operate is free to send its own `reason_code` values in `result.error` — these four only describe what the hosted worker sets. Rather than polling, a Job created with `callback_url` (and a `callback_secret` to sign it) gets this same envelope pushed to you once it reaches a terminal state — see "Receiving results by webhook" in the project-connection guide for the exact headers and a signature-verification snippet. If the runner executing your job goes dark mid-run — a crash, a dropped connection, a powered-off machine — and never reports back, the platform eventually gives up retrying and delivers a `failed` result with reason `lease_expired`, so your integration never waits forever for a runner that is not coming back. ## Governed execution is billed on BYOC too Running work through Connected Compute on a BYOC source you operate is billed for the governance plane that ran it: admission, lease and fencing, sandboxed execution, evidence, and approvals — every completed run is recorded as usage. Your own infrastructure cost stays yours; Free and Team include a monthly allowance of governed-execution seconds for work on your own hardware (not AI usage), with metered overage beyond it on Team. LumenFlow-managed compute is billed separately, per the existing managed-compute credit model. ## Private-network boundary Connected Compute is not a raw tunnel. Private-network access composes with the federation runtime and its admission gates. A BYOC source can execute approved work, but it does not silently become a private-network proxy. --- ## Desktop and mobile surfaces Category: Developer Guide URL: https://lumenflow.cloud/docs/desktop-mobile-surfaces ## One control plane, more places to operate it Desktop and mobile are projections of the same governed runtime. They do not create separate policy, evidence, or approval systems. | Surface | Current role | |---------|--------------| | **Desktop** | A Tauri 2 desktop app for the authenticated cloud routes, with device-bound sign-in storage and updater wiring | | **Mobile** | A mobile app for Sidekick chat, approvals, jobs, operations inbox, voice and notifications | ## Desktop status The desktop app includes: - authenticated cloud pages - device-bound sign-in storage in the OS keychain - automatic update wiring Desktop is useful as a governed operating surface and local-runtime container. It is not a separate product truth from the cloud control plane. ## Mobile status The mobile app includes: - Sidekick chat with approvals and jobs - operations inbox and approval drawer - Jobs artifact ledger and detail view - voice --- ## Connected Runtime Category: Developer Guide URL: https://lumenflow.cloud/docs/connected-runtime-reference-bridge ## Complete the runtime you already have A connected runtime lets teams keep a trusted external agent runtime while adding LumenFlow governance. It is not a second dashboard, a bridge-only ledger, or a public compute marketplace. The bridge proves the trusted-compute path: - external runtimes identify themselves as canonical connected activity - governed tool calls still pass through LumenFlow Rules, budgets, and approval gates - external-runtime proof lands in the same Evidence and Replay surfaces as first-party Sidekick work ## Routes A connected runtime uses the same v1 routes as other governed runtime activity: | Action | Route | Why it matters | |--------|-------|----------------| | Register | `POST /api/v1/sessions` | Establishes stable bridge session identity | | Dispatch | `POST /api/v1/sidekick/tools/[toolName]` | Sends tool requests through canonical policy, approval, and budget checks | | Evidence | `POST /api/v1/evidence` | Stores bridge-attributed receipts in the Evidence Vault | Evidence receipts submitted by a connected runtime are stamped with: - `payload.bridge_identity` — bridge kind, runtime name/version, external session, capability manifest, and acting principal when provided - `payload.bridge_session` — LumenFlow session and agent identifiers - `payload.governance_context` — approval mode, budget scope, workspace role, authority mode, or observed revision when provided ## Environment ```bash export LUMENFLOW_BASE_URL="https://lumenflow.cloud" export LUMENFLOW_API_KEY="lf_..." ``` --- ## Governed inference API Category: Developer Guide URL: https://lumenflow.cloud/docs/governed-inference ## What it is `POST /api/v1/inference` makes one typed model call and returns the answer as one JSON body. With `stream: true` it returns a `text/event-stream` instead. You name a `capability_tier` label. You never name a provider, a model, a base URL or a provider key, and you never hold a provider key. The endpoint uses the same controls as the rest of LumenFlow Cloud: a credential, limits, residency checks, a receipt for every call, and typed refusals. A refusal is never a fallback. A call never moves to a cheaper or less governed route. ## Credentials Call the endpoint with an inference-only workspace key. Its prefix is `lf_inf_` and it carries exactly one scope, `inference:invoke`. A primary workspace key, an org service token and an app key are refused with `403 insufficient_scope`. Issue and revoke inference keys as described in [Credentials and scopes](/docs/credentials-and-scopes). ```bash curl -X POST https:///api/v1/inference \ -H "Authorization: Bearer lf_inf_..." \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 7f3c2a10-5b1e-4d8a-9c2e-1a2b3c4d5e6f" \ -d '{ "capability_tier": "standard", "messages": [ { "role": "system", "content": "You summarise support tickets in one sentence." }, { "role": "user", "content": "The export button stopped working after the 3 October release." } ], "max_output_tokens": 200, "app_id": "support-desk", "caller_reference": "ticket-10482" }' ``` ## Request fields The request body is a closed schema. Any field not listed here is refused with `400 invalid_request`. A field that names a provider, model, base URL or key is listed in `error.details.fields`. | Field | Required | Meaning | | --- | --- | --- | | `capability_tier` | Yes | A label of 1 to 64 letters, digits, `.`, `_`, `:` or `-`. It must match a tier your workspace has a route for. | | `messages` | Yes | One or more messages, up to 4096 per request. Each has `role` (`system`, `user` or `assistant`) and `content`. | | `max_output_tokens` | Yes | A positive integer. It counts, with the estimated input, against the per-call token limit. | | `max_cost_usd` | No | A positive USD amount with at most six fractional digits. It is a pre-call admission cap on the provider-estimated worst-case charge. It is not a promise that the final cost stays below the cap. | | `tools` | No | One to 64 tool definitions. See Tool calling below. | | `tool_choice` | No | Needs `tools`. One of `auto`, `none`, `required`, or `{ "name": "" }`. | | `stream` | No | `true` returns a `text/event-stream`. See Streaming below. | | `app_id` | No | An opaque id of 1 to 200 printable ASCII characters. It enables per-app limits and attributes the receipt to the app. | | `end_user_id` | No | An opaque id. It is recorded on the receipt for attribution only. | | `caller_reference` | No | An opaque reference of 1 to 128 characters. It is echoed in the response and is not part of the idempotency hash. | Send `Idempotency-Key` as a header to make a retry safe. The same key with the same payload returns the stored result with the header `Idempotent-Replayed: true` and makes no second model call. The same key with a different payload returns `409 idempotency_conflict`. A call that is still running returns `409 idempotency_in_progress`. A stored result is kept for the retention limit, which is 24 hours by default, and is then cleared. ## Capability tiers and routes A tier label is resolved to a route before any provider call. The route is the workspace's own model registration that declares that tier. A workspace with no registration of its own for a tier can use a managed route for that tier where the platform offers one. Whether managed routes are enabled for a given workspace is not visible from this documentation. Check the routes listing (below) for the tiers your key can reach. ## Messages, images and cache hints Image parts are accepted in `user` messages. Content is either a string or an array of parts. A part is `{ "type": "text", "text": "..." }` or `{ "type": "image", "media_type": "image/png", "data": "" }`. - Media types are `image/png`, `image/jpeg` and `image/webp`. - `data` is canonical base64 with no line breaks. - A request carries at most 8 images. Each image decodes to at most 5 MiB and each side is at most 4096 pixels. The dimensions are read from the image header, not from the request. - A message carries at most 64 parts. Cache hints let a long, repeated prefix, such as a system prompt and a tool set, be cached by the route when the route supports it. Mark a message or a tool definition with `"cache": "ephemeral"`. The marker covers everything before it. A request carries at most 4 markers across messages and tools together. More than 4 is refused with `400 invalid_request`. A route that cannot cache accepts the markers, ignores them and serves the call normally. When the request has a marker, the response includes `cache_hint_applied` (`true` or `false`). Without markers the field is absent. Usage reports `cached_input_tokens` and `cache_write_tokens`, which are `null` when the route reports neither. ## Tool calling The endpoint carries the model side of an agent loop. Cloud never runs a tool. - **Declare.** `tools` is an array of `{ "name", "description", "input_schema" }`. A name is 1 to 64 letters, digits, `_` or `-`, starts with a letter, and is unique. `input_schema` is a JSON Schema object with `"type": "object"`. - **Respond.** When the model asks for tools, the `200` response carries `tool_calls` (each `{ id, name, arguments }`) and `finish_reason: "tool_calls"`. `text` may be empty. Run the tool in your own code. - **Send the result.** Send the next request with the assistant message's `tool_calls` and a `tool` message per call: `{ "role": "tool", "tool_call_id": "...", "content": "...", "is_error": false }`. Every result must answer exactly one earlier call. An orphan, a duplicate or a result that comes before its call is refused with `400 invalid_request`. - **Invalid calls.** A model call with an unknown name, unparseable arguments or a bad id is never returned as a tool call. It is counted in `invalid_tool_call_count`. If no valid call remains the response has `finish_reason: "tool_calls_invalid"` and no `tool_calls`. - **Bounds.** `input_schema` and `arguments` are limited to 32 levels of nesting, 2,000 keys and 1,000 enum entries. Tool names, schemas, arguments and results are never written to a receipt. The receipt records only counts. ## Streaming With `stream: true` the response is `text/event-stream` (`Content-Type: text/event-stream`, `Cache-Control: no-store, no-transform`). It is the same governed call as a single response: the same refusal order, one model call, one hold, one receipt and one settlement. - **Before the first byte.** Every refusal that is known before the response opens is an ordinary JSON error with its status code. - **Frames.** Each frame is `event: `, one `data: ` line and a blank line. The events are: - `delta` with `{ "text": "..." }`, zero or more times. - `tool_call` with `{ "id", "name", "arguments" }`, one whole assembled call. Partial argument text is never sent. - exactly one terminal event, either `usage` (the call completed, carrying the response fields other than the content, including `receipt`) or `error` (the call failed after the first byte, with `code`, `message` and `request_id`). - **Heartbeat.** While the model is silent for 15 seconds the stream sends a comment line `: keepalive`. Ignore it. - **Idle and total limits.** A stream ends with an `error` event if it runs longer than the stream duration limit or sits silent past the idle limit. Output of any kind, including a tool argument being written, resets the idle clock. The routes listing reports both limits for your key. - **Disconnect.** If your client closes the connection, the upstream call stops and is charged for the output produced, estimated from the text sent. The receipt is marked `stream.termination: "client_closed"` and `stream.usage_estimated: true`. - **Replay.** A retry with the same `Idempotency-Key` after a stream has ended replays the stored result, with no model call and no charge. A retry while the first stream is still running returns `409 idempotency_in_progress`. ## Response A single `200` response carries: - `text` and `finish_reason`. - `usage` with `input_tokens`, `output_tokens`, `total_tokens`, `cached_input_tokens` and `cache_write_tokens`. - `route` with `capability_tier`, `provider_kind` and `provider_family`. `provider_kind` is a label for the kind of route: a hosted route, or a customer-addressed endpoint. No provider or model name is returned. - `cost` with `amount` (a six-decimal string), `currency` (`USD`) and `basis`. `basis` is `managed` for a wallet-debited call, `byok_declared` or `byok_estimate` for a call on your own route where the provider bills you, or `null` when the route has no known price. - `receipt` with `id`, `recorded` and `signed`. - `caller_reference`, when you sent one. A receipt is written for every admitted, refused or replayed call. `receipt.recorded` is `false` when a call on your own route went ahead but its receipt could not be written. Such a gap is flagged, not hidden. A call whose cost is debited from a managed wallet is refused with `503 receipt_unavailable` instead, and nothing is charged. `receipt.signed` is `true` only when the stored signature is present. ## Typed refusals Every refusal has the body `{ "request_id", "error": { "code", "message", "details?" } }`. | Code | Status | Meaning | | --- | --- | --- | | `invalid_request` | 400 | A schema violation, a provider-shaped field, or a bad `Idempotency-Key`. | | `insufficient_scope` | 403 | The key is not an inference-only key. | | `managed_not_enabled` | 403 | No registration of your own for the tier, and managed routes are not available to this workspace. | | `residency_violation` | 403 | The workspace is pinned to a region and the route is in another region, or the pin cannot be checked. | | `no_route` | 422 | No registration declares the requested tier. | | `routing_policy_refused` | 422 | The routing policy refused the route. | | `insufficient_credit` | 402 | The inference wallet cannot cover the call's hold. Refused before any model call. | | `limit_exceeded` | 429 | A per-key, per-app or per-workspace limit was reached. `details.limit` and `details.scope` say which. `Retry-After` is set. | | `provider_rate_limited` | 429 | The upstream provider returned HTTP 429 before any output. `Retry-After` is set only when a valid delay was sent. | | `idempotency_conflict` | 409 | The same key was used with a different payload, or the stored result has expired. | | `idempotency_in_progress` | 409 | The first call with this key is still running. | | `provider_error` | 502 | The provider call failed. The body does not echo provider detail. | | `platform_ceiling_reached` | 503 | The service is at capacity for this route. Retry later. | | `route_unavailable` | 503 | The route could not be read or prepared. | | `receipt_unavailable` | 503 | A wallet-debited call whose receipt could not be written. The result is withheld and nothing is charged. | | `internal_error` | 500 | An unexpected failure. No detail is returned. | Each provider call makes one generation attempt. The SDK does not retry it, and a provider failure never triggers another route. ## Routes listing `GET /api/v1/inference/routes` tells a client what it can reach before it calls. Authenticate with an inference key, or with a primary workspace key holding `read`. An app key and an org service token are refused. The reply has three parts: - `tiers`: one entry per capability tier with `capability_tier`, `reachable`, `source_kind`, `priced`, `input_modalities` and `max_output_tokens`. - `limits`: the effective limits for the calling key: `tokens_per_call`, `tokens_per_day`, `spend_usd_per_day`, `requests_per_minute`, `concurrent_calls`, `stream_max_duration_seconds` and `stream_idle_timeout_seconds`. - `ceilings`: the most the key or its workspace may set the two stream limits to. It never returns a provider, a model, an endpoint, a region or a credential. Errors are `503 route_unavailable` with a retry message. ## Keys and limits Inference keys belong to a workspace. A workspace owner or admin session can manage them. A primary workspace key with the `write` scope can also mint and revoke keys, but only for its own workspace and only the keys it minted. | Action | Route | Who can call it | | --- | --- | --- | | Mint a key | `POST /api/v1/workspaces/{workspaceId}/inference-keys` with `{ "name", "scopes"? }` | Owner or admin session, or the primary key with `write`. | | List keys | `GET /api/v1/workspaces/{workspaceId}/inference-keys` | Owner or admin session. Returns display metadata only, never a key or a hash. | | Revoke a key | `DELETE /api/v1/workspaces/{workspaceId}/inference-keys/{keyId}` | Owner or admin session, or the primary key for the keys it minted. | | Read a key's limits | `GET /api/v1/workspaces/{workspaceId}/inference-keys/{keyId}/limits` | `read` or an owner or admin session. | | Set a key's limits | `PUT /api/v1/workspaces/{workspaceId}/inference-keys/{keyId}/limits` | `limits:write`, or an owner or admin session. | The plaintext key is returned once, at mint, with a notice that it cannot be retrieved again. Only its hash is stored. A primary workspace key that mints is refused with `409 inference_key_cap_reached` when the workspace already holds its limit of active keys. The reply names the limit. Limits resolve in order: the key, then the workspace, then the organisation, then the tier and the platform. Each value comes with its source and its ceiling. | Action | Route | | --- | --- | | Workspace limits | `GET` and `PUT /api/v1/workspaces/{workspaceId}/inference-limits` | | Per-subject budgets | `GET`, `PUT` and `DELETE /api/v1/workspaces/{workspaceId}/inference-limits/subjects/{subject}` | A `PUT` body is `{ "limits": { "": }, "reason": "..." }`. The reason is up to 500 characters. A value above its ceiling is clamped, and the reply lists every clamp. Each change is audited with the actor and the old and new values. The self-service limit keys are `inference.tokens_per_call`, `inference.message_chars`, `inference.request_body_bytes`, `inference.tokens_per_day`, `inference.spend_usd_per_day`, `inference.stream_max_duration_seconds`, `inference.stream_idle_timeout_seconds` and `inference.max_output_tokens`. Other limits are set by the platform operator. A per-subject budget applies to one consumer-asserted `subject`. It limits `inference.tenant.tokens_per_day` and `inference.tenant.spend_usd_per_day` for that subject. The subject is never used to decide who may call the endpoint. A subject with no budget of its own reads its source as `default`. ## Receipts and cost Every call writes one receipt. A receipt holds the calling key's id (never the key), the resolved labels, token counts, latency, the gate outcome (`permit`, `refuse` or `replay`), the refusal code if there was one, the routing decision, `app_id` and `end_user_id` when you sent them, and a cost block for admitted calls. Your prompt, your completion, your credentials and any provider key are never written to a receipt, a log or an error body. Cost is reported per call on the response (`cost`). The receipts are the record of spend. Spend is grouped by day or by `caller_reference` through the costs endpoint. --- ## Jobs lifecycle: queue, retries and dead letters Category: Developer Guide URL: https://lumenflow.cloud/docs/jobs-lifecycle ## The statuses A job reads one of six statuses from `GET /api/v1/sidekick/jobs/{id}`, or from the status events of its stream. The status is the caller-facing vocabulary. Internal states are mapped onto it. | Status | Meaning | Terminal | | --- | --- | --- | | `queued` | Accepted and waiting for a slot, or waiting out a retry backoff. | No | | `running` | A runner or the hosted worker has the job. | No | | `needs_approval` | Paused for an approval or a decision. It is not finished. | No | | `succeeded` | Finished with a result. | Yes | | `failed` | Finished with an error. A job that used its retries is also `failed`, and it is listed as a dead letter. | Yes | | `cancelled` | Stopped by its owner. Always distinct from `failed`. | Yes | A terminal job sends one result to its callback, if it has one, and its `result_envelope` is set. Before a job is terminal, `result_envelope` is `null`. ## Queueing and position Creating a job with `POST /api/v1/jobs` returns `202` and the job starts as `queued`. The same `Idempotency-Key` with the same body returns `200` with the original `job_id`. The same key with a different body is refused. Jobs wait in one queue per tenant and take turns with other tenants, so one tenant's backlog does not hold back another. While a job is `queued` its status read carries: - `queue_position`: its place in its own tenant's queue, where `1` is next. It is `null` when the job is not queued. - `jobs_ahead`: an estimate of how many claimable jobs the claim would hand out before this one, across the whole claim pool the job competes in. It is a count only and names nothing of any other tenant. It is capped at a platform limit. Above the cap, `jobs_ahead` reads the cap and `jobs_ahead_capped` is `true`. - `started_at`: when the job first started. It is kept when a lost worker returns the job to the queue. The stream sends a new `status` event each time the position moves. ## Concurrency, tenants and exclusive groups - **Tenant concurrency.** A job over its tenant's concurrent-run cap is accepted and reads as `queued`. It starts when a slot frees. - **The only queue refusal.** A workspace whose queue has reached its ceiling is refused with `429 queue_saturated` and a `Retry-After` header. A tenant whose own queue is full gets the same status with a tenant scope. - **Exclusive groups.** Set `exclusive_group` on create to name work that must not run at once. It is an opaque label of 1 to 200 printable ASCII characters. When the workspace limit `jobs.exclusive_group_max` is set, a job whose group already has that many running is skipped by the claim. It is never waited on, so jobs in other groups, and jobs with no group, are handed out past it. Unset is unlimited. - **Limits.** A cap that is not set is unlimited. A job whose `max_cost_usd` is above the platform cap is refused with `max_cost_usd_exceeds_cap`. ## Retries A job created with a `retry` policy runs again after a retryable failure. The policy is: ```json { "retry": { "max_attempts": 4, "base_delay_s": 5, "max_delay_s": 300, "retry_on": ["provider_timeout"], "deadline_s": 3600 } } ``` - `max_attempts` is at least 1. It may not exceed the platform cap for the job's kind. - `base_delay_s` is the first backoff. It may not be below the platform minimum, which is 1 second unless the platform sets it higher. A policy that names no delay waits 5 seconds, doubling, and never more than 5 minutes. - `max_delay_s` caps the backoff. It may not be below `base_delay_s`. - `retry_on` limits retries to the failure codes you name in `error.reason_code`. When it is absent, any retryable failure is retried. - `deadline_at` (an ISO 8601 time) or `deadline_s` (seconds after the first attempt starts) sets an overall deadline. Not both. The deadline may not be further ahead than the platform maximum, which is 7 days by default. After failed attempt `n`, the job waits `min(max_delay_s, base_delay_s * 2^(n-1))` seconds, jittered to between half of that and the whole of it. The claim never hands the job out before then. The status shows `next_attempt_at`, and `attempt_count` counts how many times the job has been started in its current attempt chain. These failures are terminal and are never retried: `budget_exhausted`, `secret_in_diff`, `duration_exceeded`, and any reason code that ends in `_refused`. A policy above the platform caps is refused with `400 retry_policy_exceeds_cap`. A malformed policy, or a `base_delay_s` below the minimum, is refused with `400 invalid_retry_policy`. A failed job with a retry policy is retried until it succeeds or uses its attempts. A tenant may use a limited number of retries per window, set by the platform. Past that budget a failed job is dead-lettered with reason `retry_budget_exhausted`, and no other tenant is affected. ## Deadlines When the deadline has passed, or when the next backoff would start a retry after it, a failing job is dead-lettered with reason `deadline_exceeded`, whatever attempts are left. An attempt already running at the deadline finishes or fails normally. An expired lease counts as a failing job. ## Dead letters A dead letter is a job that used its retry attempts, or failed terminally under a retry policy, and is waiting for its owner to requeue or discard it. Its status stays `failed`. `GET /api/v1/jobs/dead-letters` lists them, newest first. Each entry carries `reason`, `attempt_count` and `last_error.reason_code`. The `reason` is a free string. The reasons in use are `attempts_exhausted`, `terminal_error`, `retry_not_allowed`, `retry_budget_exhausted` and `deadline_exceeded`, and more may be added. Page with `limit` (1 to 200, default 50) and the opaque `cursor`. A workspace key sees only the dead letters of the tenant it names, in the `X-Tenant-Subject` header or the `tenant_subject` query parameter. A tenant-scoped key that names no tenant is refused with `400 tenant_subject_required`. A dead letter of a job with no tenant is listed to a key that names no tenant, but that key cannot requeue or discard it. A workspace member can. Resolved dead letters, and their attempt records, are deleted after the dead-letter retention period, 30 days by default. ## Requeue `POST /api/v1/jobs/{id}/requeue` puts a dead letter back on the queue as a new attempt chain. The attempt count starts again. The job's last checkpoint is kept, so a step it already finished is not repeated. From a workspace key the body must carry `tenant_subject`, `actor_kind` and `actor_ref`. Without them the request is refused with `403 actor_attestation_required`. Another tenant's job, or a job that is not a dead letter, is `404`. A tenant that has used its retries for the window is refused with `429 rate_limited` and `Retry-After`. No other tenant is affected. ## Discard `DELETE /api/v1/jobs/{id}/dead-letter` discards a dead letter. It leaves the list and the job stays `failed`. The same tenant and actor rules apply as for requeue. ## Stopping a job `POST /api/v1/jobs/{id}/controls` with `{ "action": "cancel" }` stops a job. A cancelled job reads `cancelled`, with `cancelled_at` set once. It is never retried, dead-lettered or claimed again. Its callback and its stream carry `cancelled`. ## Runner claims, waits and delays A runner gets work with `POST /api/v1/runtime/claim`. - **Waiting for work.** The body may carry `wait_seconds`, a whole number of seconds, 0 or more. The default is 0, which is a plain claim. When nothing is claimable the request is held up to that many seconds and returns the first job that becomes claimable. The wait is capped by the `jobs.claim_max_wait_seconds` limit, 20 seconds by default. A value that is not a whole number is refused with `400 invalid_wait_seconds`. - **Giving the claim back.** A runner that cannot proceed yet calls `POST /api/v1/assignments/{id}/release` with `not_before` (an ISO 8601 time) or `delay_s` (seconds from now), never both. The lease is freed at once. The job returns to the queue as `queued`, with `next_attempt_at` set, and it is not claimable before then. A release does not count as an attempt, and the last checkpoint is kept. The time must be in the future, no further ahead than the `jobs.release_max_delay_s` limit (86400 seconds by default), and before the job's retry deadline. A job released too often is refused with `429 rate_limited`. A release never dead-letters a job. ## Leases, heartbeats and lapse A runner holds a lease on the job it runs. It keeps the lease with `POST /api/v1/assignments/{id}/extend`, a heartbeat that may carry a `checkpoint` with `seq`, `step_id` and `completed_step_ids`. A re-claimed job resumes after its last recorded checkpoint. A run longer than the limit for its job kind is refused with `409 duration_exceeded`. The job ends with that reason and keeps its last checkpoint. A lease that is not extended lapses. The job returns to the queue within the lapse bound: - on the next claim in the same workspace once the lease expired more than a short grace period ago; - with no claims at all, through a periodic reconciler. A lapse counts an attempt, like any other failure. A late extend, complete or fail from the lapsed holder is refused, or changes nothing. ## Workspace limit | Limit | Default | Governs | | --- | --- | --- | | `jobs.exclusive_group_max` | unset (unlimited) | Running jobs allowed in one exclusive group. | Your workspace can read and change this limit through the job limits route, `GET` and `PUT /api/v1/workspaces/{workspaceId}/job-limits`, bounded by the platform ceiling for it. --- ## Enterprise Trust Category: Developer Guide URL: https://lumenflow.cloud/docs/enterprise-trust ## What enterprise trust provides Enterprise trust is an **additive, org-scoped** governance layer on top of the workspace control plane. It provides visibility into trust posture, enterprise auth readiness, and compliance controls. ## Trust dashboard The trust page at `/dashboard/trust` is visible only to workspace operators (owner or admin role). It shows: - **Live controls**: Evidence Vault, compliance export, and enterprise auth (SAML sign-in, SCIM provisioning, MFA policy) — operational today - Operator workspace count in scope - Governance root confirmation (workspace-scoped, additive) > **info** > Enterprise trust does not bypass workspace governance. Admin and > reviewer roles cannot override workspace-level approvals or policies. ## Enterprise auth configuration SSO, SAML and SCIM are live controls. `GET /api/v1/enterprise` returns the current configuration and readiness. | Feature | Status | Notes | |---------|--------|-------| | **SAML sign-in** | Live | Verifies your identity provider's signed assertion, with a bounded clock-skew window and replay protection, before starting a session | | **SCIM provisioning** | Live | Create, list, update, and deactivate users and groups over a per-workspace bearer token | | **MFA policy** | Live | Require step-up authentication for enterprise-admin actions, toggle per org | ### SAML sign-in When SAML is enabled, `GET /api/v1/enterprise/saml/metadata` returns SP metadata XML with entity ID and ACS URL for your identity provider configuration. `POST /api/v1/enterprise/saml/acs` verifies your identity provider's signed response and starts the session. Every sign-in attempt, accepted or rejected, is recorded in a forensic sign-in log. ### SCIM provisioning `POST`/`GET /api/v1/enterprise/scim/Users` (and the matching `/Groups` endpoints) create, list, update, and deactivate users and groups per RFC 7644, authenticated with a per-workspace bearer token. Every provisioning action is recorded in a forensic audit log. ## Access control All enterprise endpoints require the **org-operator** role — the user must be an owner or admin in at least one workspace within the org. Non-operators receive 403. ## Readiness model Enterprise auth readiness is dynamic, derived from actual org configuration: | Readiness | Meaning | |-----------|---------| | **Live today** | Feature is enabled and operational | > **info** > There is no pre-built integration for a specific identity provider. > Any RFC-compliant identity provider can be used. --- ## Evidence Vault Category: Developer Guide URL: https://lumenflow.cloud/docs/evidence-vault ## What the Evidence Vault provides The Evidence Vault is the canonical store for proof of what governed agents did — every tool invocation, scope decision, and I/O hash. ## Evidence receipts Each governed action produces an evidence receipt: | Field | Purpose | |-------|---------| | `scope_requested` | What the agent asked to do | | `scope_allowed` | What policy permitted | | `scope_enforced` | What actually happened | | `io_hash` | Cryptographic hash for integrity verification | Ingest via `POST /api/v1/evidence`. Query via `GET /api/v1/evidence`. ## Observe integration The Observe dashboard at `/dashboard/observe` shows per-workspace: - Evidence receipt count and governed task count - **Export-ready** or **Awaiting evidence** status badge - Compliance export source badges and linked export path ## Compliance export Export workspace data for compliance with `GET /api/v1/export?format=json` (or `csv`). The export includes: - Evidence receipts with scope and I/O hashes - Kernel events (task lifecycle) - Telemetry metrics - Access review data Export is workspace-scoped and requires workspace membership. ## Retention Evidence retention follows workspace tier: | Tier | Retention | |------|-----------| | **Free** | 7 days | | **Team** | 90 days | | **Enterprise** | 365 days | Stored data is removed when the tier's retention period ends. --- ## Approval Workflows Category: Developer Guide URL: https://lumenflow.cloud/docs/approval-workflows ## What approvals provide Approvals gate risky actions behind human review. They cover budget overrides, autonomy exceptions, routine decisions, and sensitive operator controls. ## Creating approvals `POST /api/v1/approvals` creates an approval request. The system also creates approvals automatically when governed actions trigger approval-required policies. ## Resolving approvals `POST /api/v1/approvals/{id}` resolves an approval: | Decision | Effect | |----------|--------| | **approve** | Action proceeds | | **reject** | Action is blocked with reason | Include an optional `comment` and `reason` with the decision. ## Discussion threads `POST /api/v1/approvals/{id}/comments` adds a comment to the approval discussion. Comments are timestamped and attributed to the commenting user. ## Approval types Common approval types: | Type | Raised for | |------|------------| | `operator_control` | Sensitive operator actions such as requeue, reassign and abort | | `sidekick_tool_approval` | Approval for a Sidekick tool call | | `app_connector_call` | Approval for an app connector call | Sensitive approvals carry a four-eyes rule. The requester of one of these approvals cannot decide it. A decision is single winner. Once one decision is recorded, a concurrent decision is refused, and the approval is not decided twice. ## Operator-control approvals When workspace governance requires approval, sensitive actions such as requeue, reassign and abort wait for a decision before they run. Other actions run directly. ## Dashboard The approvals inbox now lives inside the Sidekick chat surface as a widget — ask Sidekick to show pending approvals and the inbox renders inline with decision buttons and discussion threads. Approval policy (which actions pause for sign-off) lives at `/dashboard/{workspaceId}/settings#approvals`. ## Transition history Every approval state change (created, approved, rejected) is recorded in the transition history with timestamp, actor, and reason. --- ## Connect a project to LumenFlow Cloud + consume the API Category: Developer Guide URL: https://lumenflow.cloud/docs/connect-project > **warning** > This walkthrough issues an **advanced workspace API key** — the strongest > credential in a workspace, meant for CI jobs and self-hosted automation. > It is not part of the consumer setup journey and is not how you pair your > own Linux or Windows machine as a Connected Compute node: that flow lives > on the workspace **Compute** page and uses a short-lived, single-use > pairing code instead of any long-lived token. Use this page only when you > are automating a repository or CI runtime against the Sidekick API. > **info** > Prefer a guided experience? The dashboard ships an in-app wizard that > walks the same six steps in order: open > [`/dashboard/connect`](/dashboard/connect) while signed in. The wizard > issues the API key, copies the connect command, previews > `workspace.yaml`, and probes `/api/v1/health` for you. ## Two auth surfaces LumenFlow Cloud exposes two parallel bearer-token surfaces. Pick the one that matches what your consumer needs to do: | Surface | Use case | Auth header | | --- | --- | --- | | **Workspace API key** | Run Sidekick, dispatch tools, manage agents/jobs/memory/runtime sessions | `Authorization: Bearer ` | | **Engagement token** | Read-only cross-project consumption: overview, work, evidence, events, snapshots, embeds, OpenAPI introspection | `Authorization: Bearer ` per engagement slug | Workspace API keys are issued per workspace and act on its behalf. Engagement tokens are scoped to a single engagement (a curated view onto a workspace for an external consumer — your customer portal, a partner integration, an embedded dashboard). Two more kinds of key sit beside these: inference keys for governed model calls, and app keys for a deployed app's server. Runner onboarding grants and org service tokens are the remaining kinds. The prefix, scopes and revoke path of every kind are in [Credentials and scopes](/docs/credentials-and-scopes). ## Step 1 — Create a workspace Sign in at `https:///dashboard` and create a workspace. Note the workspace ID (UUID) and your org ID — both show up in the workspace settings page. ## Step 2 — Issue a workspace API key From the dashboard, hit the **Regenerate API key** button on the workspace settings page, or call the endpoint directly: ```bash curl -X POST https:///api/v1/workspaces//api-key \ -H "Authorization: Bearer " ``` The response includes the plaintext key, the connect command, and the full SDK enrollment descriptor: ```json { "workspaceId": "", "apiKey": "lf_xxxxxxxxxxxxxxxxxxxx", "orgId": "", "connectCommand": "npx lumenflow cloud connect --endpoint https:// --org-id --project-id --token-env LUMENFLOW_CONTROL_PLANE_TOKEN", "sdkEnrollment": { "contractVersion": 1, "runtimeModel": "governed_external_agent", "runtimeSource": "connected", "bootstrap": { "endpoint": "https://", "orgId": "", "projectId": "", "tokenEnv": "LUMENFLOW_CONTROL_PLANE_TOKEN", "workspaceConfig": { "endpoint": "https://", "org_id": "", "project_id": "", "sync_interval": 30, "policy_mode": "tighten-only", "auth": { "token_env": "LUMENFLOW_CONTROL_PLANE_TOKEN" } } } } } ``` The plaintext `apiKey` is shown **once**. Store it in a secrets manager immediately. If you lose it, regenerate via the same endpoint — the previous key is invalidated within ~15 seconds on every cloud instance. ## Step 3 — Connect the local project Put the key in `LUMENFLOW_CONTROL_PLANE_TOKEN` for the shell you run the command from — a hidden read, never a literal `export ...=` in a profile or in history. The command passes only the variable **name**, so it is the same on Linux, macOS and Windows: ```bash # bash / zsh (Linux, macOS) — paste the key, hidden: read -rs LUMENFLOW_CONTROL_PLANE_TOKEN && export LUMENFLOW_CONTROL_PLANE_TOKEN # PowerShell (Windows) — paste the key, hidden: $env:LUMENFLOW_CONTROL_PLANE_TOKEN = Read-Host -MaskInput 'Workspace key' ``` Then, in the root of the project you want to govern: ```bash npx lumenflow cloud connect \ --endpoint https:// \ --org-id \ --project-id \ --token-env LUMENFLOW_CONTROL_PLANE_TOKEN ``` Add `--force` to re-link a project that already has a `control_plane` block (for example after regenerating the key). Use the `npx lumenflow cloud connect` subcommand: the `pnpm cloud:connect` script that an older CLI version wrote into a consumer repo may not accept these flags. The CLI stores the key **per project** in `$LUMENFLOW_HOME/secrets/.env` (mode 0600) and writes the cloud bootstrap into your local `workspace.yaml`: ```yaml endpoint: https:// org_id: project_id: sync_interval: 30 policy_mode: tighten-only auth: token_env: LUMENFLOW_CONTROL_PLANE_TOKEN token_file: $LUMENFLOW_HOME/secrets/.env ``` Because the credential lives in a per-project file, several projects on one machine each keep their own key. Never export a workspace key from a shell profile: a global value shadows every other project's file. After this, your local LumenFlow runtime emits sessions, events, evidence and telemetry to: - `POST /api/v1/sessions` - `POST /api/v1/events` - `POST /api/v1/evidence` - `POST /api/v1/telemetry` Minimum supported kernel is **5.0.0**; the full-feature kernel is **6.0.0**. A newly connected machine needs an owner's capability approval before it can run work. Sessions, events, evidence and telemetry flow straight away, but requests to claim work are refused until a workspace owner or admin approves the machine's capabilities on the **Compute** page. The capabilities the machine asks for appear there for review, and it can then run only what you approved. ## Step 4 — Call the Sidekick API for actions With the workspace API key as bearer, hit any of the workspace-scoped endpoints. The most common is dispatching a Sidekick task: ```bash curl -X POST https:///api/v1/sidekick/chat \ -H "Authorization: Bearer $LUMENFLOW_CONTROL_PLANE_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "messages": [{ "role": "user", "content": "List today open approvals" }], "threadId": "" }' ``` Other workspace-scoped endpoints under `/api/v1/`: - `/sidekick/briefings/run` — kick off an objective briefing - `/sidekick/objectives` — read or update objectives - `/workspaces//jobs` — list jobs - `/workspaces//knowledge` — manage workspace memory - `/approvals` plus `/approvals//resolve` — approval queue - `/agents` — agent fleet - `/runtime/sessions` — runtime sessions - `/memory/nodes` plus `/memory/sync` — workspace memory All workspace endpoints carry an `X-LumenFlow-Control-Plane-SDK-Contract-Version` header back so SDK clients can detect contract drift. ### Creating a Job directly For automation that names a specific playbook or event instead of chatting, `POST /api/v1/jobs` (and its alias `POST /api/v1/intent`) create a governed Job without going through the chat surface: ```bash curl -X POST https:///api/v1/jobs \ -H "Authorization: Bearer $LUMENFLOW_CONTROL_PLANE_TOKEN" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: " \ -d '{ "workspace_id": "", "kind": "area-signoff", "required_capabilities": ["local-tool-exec"], "params": { "site": "north-yard" }, "callback_url": "https://your-app.example/lumenflow-result", "callback_secret": "a-shared-secret-you-generate" }' ``` `kind` names what you're asking for; `required_capabilities` is what a runtime must be approved for to run it — they are never inferred from each other. Whether the Job runs as a connector action against one of your connected apps or as managed output is resolved automatically from what you send (a connector-shaped `params.invocation`, or a capability you already have a connected app for): a `managed_artifacts` Job runs on the hosted runtime, and any other capability set runs on a Connected Compute node that advertises it. You never name an executor. Whatever you send in `params` (capped at 64 KiB of JSON) reaches your runner as structured data on the assignment it claims — never re-parsed out of a description — so it can read a field like `params.repo_url` directly and hand back a field like `params.correlation` unchanged in its result. A `managed_artifacts` Job is real work, not a draft placeholder: the hosted runtime generates the artifact and reaches `status: "succeeded"`, with `result_envelope.artifact_refs` pointing at what it produced. It's billed the same way a Sidekick chat turn is billed — as a normal model call against your workspace's configured model, no separate compute charge. `callback_url` gets one signed POST when the Job finishes, signed with `callback_secret` so you can verify it — the two must be sent together, since there's no way to sign a callback without a secret. Omit both and poll `GET /api/v1/sidekick/jobs/` instead. `Idempotency-Key` makes retries safe: resend the same key with the same body and you get back the original Job instead of a duplicate; resend it with a different body and the request is refused. ### Listing the connector catalogue To render a connector picker without hard-coding provider names, `GET /api/v1/sidekick/catalog` returns the catalogue and the kinds your key can add. It needs a workspace key with read scope; an inference-only key is refused. ```bash curl "https:///api/v1/sidekick/catalog?availability=ready" \ -H "Authorization: Bearer $LUMENFLOW_CONTROL_PLANE_TOKEN" ``` `entries` is ordered by `provider`; each has `kind` (`channel`, `tool_connection` or `event_source`), `display_name`, `availability` (`coming_soon`, `limited` or `ready`), `auth_kind`, its `capabilities` and `risky_capabilities`, a `setup_hint_kind`, a `source` (`built-in`, `operator-added` or `workspace-added`; a workspace-added entry is visible only to its own workspace) and a `connect_mode` (`attempt`, `owner_form` or `operator_only`) that says whether a connector needs an operator to connect it. Starting a connection with a key is not available yet. No credentials or endpoints are ever returned. Filter with `kind`, `availability` and `source`; an unknown value is a 400 with code `invalid_filter`. `install_kinds` lists the kinds a workspace can add, each with its install route and `installable_by_key`. When it is `false`, send the user to an operator: that kind needs a signed-in member. ### Listing the connections an end user holds `GET /api/v1/sidekick/tool-connections` returns the tool connections visible to one scope. It needs a workspace key with read scope; an inference-only key is refused, and so is an app key (the app-key scope for this route is not available yet). ```bash curl "https:///api/v1/sidekick/tool-connections" \ -H "Authorization: Bearer $LUMENFLOW_CONTROL_PLANE_TOKEN" \ -H "X-Tenant-Subject: " ``` Send `X-Tenant-Subject` (the same opaque id you use on Jobs) to list one end user's connections. Leave it out to list only the connections that belong to the app itself. An end user never sees another end user's connections, and a connection that belongs to someone else is not an error, it is simply not in the list. Each connection has `id`, `connectorKey`, `provider`, `status` (`connected`, `needs_reconnect` or `revoked`), `enabled`, `accountLabel`, `grantedScopes`, `revision`, `createdAt` and `updatedAt`. No token, account id or handle is ever returned. Filter with `connectorKey` and `status`; an unknown status is a 400 with code `invalid_filter`, and a malformed `X-Tenant-Subject` is a 400 with code `invalid_tenant_subject`. This route only lists: connecting an end user's account from your app is not available yet. ### Receiving results by webhook When the Job reaches a terminal state, `callback_url` receives one delivery chain: the first attempt arrives within seconds of completion; failed attempts are retried with backoff up to 6 attempts, then dead-lettered (never retried past one attempt on a 4xx). The body is the same result envelope `GET /api/v1/sidekick/jobs/` returns. Three headers ride the request: | Header | Contents | | --- | --- | | `X-Lumenflow-Signature` | `t=,v1=`, keyed with your `callback_secret` | | `X-Lumenflow-Timestamp` | Unix seconds when this attempt was sent — equal to the `t` inside `X-Lumenflow-Signature` | | `X-Lumenflow-Delivery-Id` | Stable per delivery attempt-chain — the same value on every retry of the same result | Verify it before trusting the body — recompute the HMAC yourself and reject anything that doesn't match, and reject a stale timestamp (more than 5 minutes from your own clock) so a captured request can't be replayed later. The header always carries exactly one `v1` value today, signed with the one `callback_secret` your Job was created with — there's no secret rotation to handle yet. **Node.js** ```js import { createHmac, timingSafeEqual } from "node:crypto"; function verifyLumenflowCallback({ secret, rawBody, signatureHeader }) { const match = /^t=(\d+),v1=([0-9a-f]+)$/.exec((signatureHeader ?? "").trim()); if (!match) return false; // wrong shape — reject const [, t, providedHex] = match; const ageMs = Date.now() - Number(t) * 1000; if (!Number.isFinite(ageMs) || Math.abs(ageMs) > 5 * 60 * 1000) { return false; // stale or clock-skewed — reject } const expectedHex = createHmac("sha256", secret) .update(`${t}.${rawBody}`) .digest("hex"); const a = Buffer.from(providedHex); const b = Buffer.from(expectedHex); return a.length === b.length && timingSafeEqual(a, b); } ``` **Python** ```python import hashlib import hmac import re import time def verify_lumenflow_callback(secret: str, raw_body: bytes, signature_header: str) -> bool: match = re.fullmatch(r"t=(\d+),v1=([0-9a-f]+)", (signature_header or "").strip()) if not match: return False # wrong shape — reject t, provided_hex = match.group(1), match.group(2) if abs(time.time() - int(t)) > 5 * 60: return False # stale or clock-skewed — reject expected_hex = hmac.new( secret.encode("utf-8"), f"{t}.".encode("utf-8") + raw_body, hashlib.sha256, ).hexdigest() return hmac.compare_digest(provided_hex, expected_hex) ``` Use the exact raw request body bytes (not a re-serialized `JSON.stringify`/`json.dumps` of the parsed object) when recomputing the HMAC, or a byte-for-byte-identical payload will still fail to verify. ## Step 5 — Consume the engagement-projection API (read-only, cross-project) The engagement-projection surface is the **mission control** model. You provision an **engagement** in cloud — a curated read-only view onto a workspace shaped for an external consumer — and issue them an engagement token. They then read from a fixed surface that the workspace admin can introspect via auto-generated OpenAPI per engagement. ```bash # Get the OpenAPI spec for this engagement (auto-generated) curl https:///api/v1/engagements//openapi.json \ -H "Authorization: Bearer " ``` The 13 endpoints under `/api/v1/engagements//`: | Endpoint | Returns | | --- | --- | | `/overview` | Engagement summary | | `/work` | Work units plus delivery state | | `/capabilities` | Capability inventory | | `/agents` | Agent fleet | | `/architecture` | Architecture read-model | | `/approvals` | Approval queue (read-only) | | `/evidence` | Evidence stream | | `/events` | Paginated event log | | `/events/live` | Server-Sent Events live stream | | `/documents` | Document index | | `/snapshots` | Point-in-time exports | | `/embed-token` | Signed embed token (for iframe-style embeds) | | `/openapi.json` | Auto-generated OpenAPI spec for this engagement | Every response goes through a visibility-policy filter — the engagement owner controls what each engagement token can see; raw workspace state is never exposed without explicit projection. ## Step 6 — Embed an engagement view For dashboards inside your own product (a customer portal, a partner console), issue a signed embed token and iframe the returned URL: ```bash curl -X POST https:///api/v1/engagements//embed-token \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "surface": "overview", "ttlSeconds": 900 }' ``` Response includes an `embedUrl` and `expiresAt`. The signed URL carries the visibility scope and renders LumenFlow's engagement UI inline in your product. ## Step 7 — Server-to-server webhooks LumenFlow can push events outward when something changes — a job completes, an approval lands, an evidence record is anchored. Configure delivery targets per workspace; cloud signs each payload with HMAC so your receiver can verify provenance. See `/api/v1/engagements//events` for the canonical event catalog and the per-engagement webhook configuration UI in the dashboard. ## Verifying the connection Once `workspace.yaml` is in place and your local runtime starts emitting: - The dashboard `/observe` page shows the first runtime session appear within 30 seconds (the default `sync_interval`). - `/api/v1/health` from your bootstrap returns `{ status: "ok", workspace: "" }`. - The workspace **Recent activity** card surfaces the first event. If nothing appears, check that `$LUMENFLOW_HOME/secrets/.env` exists for this project (or that `LUMENFLOW_CONTROL_PLANE_TOKEN` is present in the environment that runs the local runtime), and that the workspace API key has not been regenerated since `cloud connect` last ran. After a regeneration, re-run `npx lumenflow cloud connect --force ...` in that project. ## Auth model recap | Token kind | Issued via | Scope | Revoke | | --- | --- | --- | --- | | Workspace API key | `POST /api/v1/workspaces//api-key` | Workspace-scoped actions under `/api/v1/`, limited to the key's scopes (`read`, `write` and any opt-in scope named at issue) | `DELETE` on the same endpoint; other instances may keep accepting it for up to 15 seconds | | Inference key | `POST /api/v1/workspaces//inference-keys` | Only `inference:invoke`, for governed model calls | `DELETE /api/v1/workspaces//inference-keys/` | | App key | `POST /api/v1/workspaces//app-keys` | The declared app scopes only, never `read` or `write` | `DELETE /api/v1/workspaces//app-keys/`; refused on its next use | | Org service token | `POST /api/v1/orgs//service-tokens` | Org-wide reads (`read`), plus the opt-ins `workspaces:manage` and `members:manage` | `DELETE /api/v1/orgs//service-tokens/` | | Runner onboarding grant | `POST /api/v1/workspaces//runner-onboarding/grants` | The `runner:onboard.*` scopes, for runner onboarding endpoints only | `DELETE /api/v1/workspaces//runner-onboarding/grants/`; refused on its next use | | Engagement token | Per-engagement provisioning in dashboard | One engagement, read-only, visibility-policy filtered | Engagement settings page; immediate | | Signed embed token | `POST /api/v1/engagements//embed-token` | Single surface, single TTL | Expires on TTL; revoke parent engagement to invalidate early | | Dashboard JWT | Dashboard sign-in on `/dashboard` | UI actions only | Sign-in session expiry | The workspace API key is the strongest credential — treat it like a service-account key. Engagement tokens are safer to share externally because their visibility is bounded by the engagement projection configuration. ## Where to go next - **Approval Workflows** — gate risky actions behind human review - **Agent Fleet Management** — manage runtime agents per workspace - **Webhook Integrations** — push events outward to your own systems - **Sidekick Tools Reference** — the ~33 named tools Sidekick can dispatch from chat - [**Connected Compute**](/docs/connected-compute) — pairing your own Linux or Windows machine to run Sidekick work uses a separate, short-lived pairing code rather than this workspace API key --- ## Dashboard Overview Category: Dashboard Guide URL: https://lumenflow.cloud/docs/dashboard-overview ## Your command center The dashboard is the first thing you see after signing in. By default the workspace root opens **Sidekick** — the conversation surface where you ask for outcomes, review plans, approve actions, and see proof inline as widgets. ## Layout The dashboard has a sidebar for navigation and a main content area that changes based on your current page. The header includes search and notifications. ## Sidebar navigation | Section | Purpose | |---------|---------| | **Sidekick** | The conversation. Ask, plan, approve, review outputs and proof inline as widgets — this is the front door. | | **Jobs** | Workspace-level overview of jobs and recent activity for users who want a non-conversational list view. | | **Agents** | Operator depth surface for job and runtime state — job graph, safe operator actions, outputs, live runtime activity. | | **Observe** | Audit trail, analytics, and evidence vault. | | **Settings** | Workspace configuration: team, billing, connections, rules, approvals, notifications, API keys, model defaults, memory preferences. | ## Quick actions From any workspace you can: - Ask Sidekick for an outcome and watch the plan, approvals, outputs, and proof render inline - Drill into Jobs for a non-conversational list of jobs - Check token usage, budgets, and connections from Settings - Manage team member access from Settings > **info** > The dashboard adapts to your role. Admins see team management, > billing, and operator surfaces; members see their own conversations, > approvals, and evidence. --- ## Workspace Management Category: Dashboard Guide URL: https://lumenflow.cloud/docs/dashboard-workspace-management ## What is a workspace? A workspace is an isolated environment with its own conversations, connections, governance rules, and billing. Use separate workspaces for different teams, projects, or clients. ## Creating a workspace 1. Click the workspace selector in the top-left corner 2. Select **New Workspace** 3. Enter a name and optional description 4. Choose your plan tier ## Switching workspaces Click the workspace selector to see all workspaces you belong to. Switch instantly — each workspace retains its own state. ## Workspace settings | Setting | Description | |---------|------------| | **Name** | Display name for the workspace | | **Description** | Optional context for team members | | **Default model** | LLM model used for new conversations | | **Timezone** | Used for scheduled workflows and reporting | ## Deleting a workspace Go to **Settings → General → Danger Zone** and click **Delete Workspace**. This action is irreversible and removes all conversations, connections, and audit data. > **warning** > Only workspace owners can delete a workspace. > Transfer ownership first if the current owner is leaving. --- ## Activity feed and proof Category: Dashboard Guide URL: https://lumenflow.cloud/docs/dashboard-activity-feed ## Where activity lives now The legacy `/sidekick/activity` list view is gone. The same information now surfaces through three places: - **Sidekick Proof widget** — ask "what just happened?" or "show me the audit trail" and Sidekick renders the event stream inline with replay deep-links - **Notifications** (the workspace bell, configured at **Settings → Notifications**) — covers the live "something just happened" stream - **Jobs → Job → Proof** — per-job audit feed for operator drill-down, the Proof section on the job detail page (`/dashboard//jobs/`) ## Event types | Event | Icon | Description | |-------|------|------------| | **Action executed** | ● | Sidekick completed an approved action | | **Proposal created** | ◐ | Sidekick is requesting approval | | **Proposal approved** | ✓ | An action was approved (manual or auto) | | **Proposal rejected** | ✕ | An action was rejected | | **Connection event** | ⇄ | A service was connected or disconnected | | **Governance change** | ⚙ | A rule was created or modified | ## Filtering In the job detail page's Proof section you can narrow the stream: - **By type** — show only proposals, actions, or governance events - **By connection** — filter to a specific service (Gmail, Slack, etc.) - **By user** — see activity from a specific team member - **By date range** — focus on a specific time period ## Real-time updates Activity feeds update in real time. New events appear at the top with a subtle animation. > **info** > The activity feed is read-only. To take action on a pending > proposal, ask Sidekick to show the Approvals widget — you can approve or > deny inline without leaving the conversation. --- ## Analytics & Reporting Category: Dashboard Guide URL: https://lumenflow.cloud/docs/dashboard-analytics ## Analytics overview Navigate to **Observe → Analytics** to see workspace-level metrics and trends. ## Key metrics ### Token usage Track how many tokens your workspace consumes: - **Daily breakdown** — bar chart of tokens per day - **By model** — which LLM models are used most - **By action type** — email drafts vs. calendar queries vs. research ### Action volume | Metric | Description | |--------|------------| | **Total actions** | All executed actions in the period | | **Auto-approved** | Actions that matched a governance rule | | **Manually approved** | Actions that required human review | | **Rejected** | Actions that were rejected | ### Approval rate The percentage of proposals that are approved. A high rejection rate may indicate prompting issues or overly broad Sidekick behavior. ## Exporting data Click **Export** to download analytics as CSV: - Token usage by day - Action log with timestamps - Cost breakdown by category ## Date ranges Use the date picker to analyze specific periods: - Last 7 days (default) - Last 30 days - Custom range > **success** > Use analytics to identify patterns. If a specific action type > dominates token usage, consider setting a cost cap for it. --- ## Team Members Category: Dashboard Guide URL: https://lumenflow.cloud/docs/dashboard-team-members ## Managing your team today There is no dashboard Team screen yet. Workspace membership — invites and roles — is managed through the API by a workspace owner or admin. ## Roles | Role | Permissions | |------|------------| | **Owner** | Full access, billing, can delete workspace | | **Admin** | Manage connections and governance rules, invite members | | **Member** | Use Sidekick, manage own conversations | | **Viewer** | Read-only access | ## Inviting a member An owner or admin calls: ``` POST /api/v1/workspaces//invites { "email": "person@example.com", "role": "member" } ``` The response includes a one-time accept URL. Hand that link to the invitee directly, or rely on the invite email LumenFlow sends — if delivery fails, the accept URL in the response still works. ## Removing members or transferring ownership Neither has a dashboard control today; both go through the workspace membership API. Their conversations and audit trail are preserved regardless. --- ## Workspace Settings Category: Dashboard Guide URL: https://lumenflow.cloud/docs/dashboard-settings ## General settings Navigate to **Settings → General** to configure workspace-level defaults. ## Available settings ### Display | Setting | Description | Default | |---------|------------|---------| | **Workspace name** | Shown in sidebar and workspace selector | Required | | **Description** | Optional team context | Empty | | **Timezone** | Used for schedules and timestamps | UTC | ### AI behavior | Setting | Description | Default | |---------|------------|---------| | **Default model** | LLM model for new conversations | Provider default | | **Temperature** | Creativity level (0.0–1.0) | 0.7 | | **Max tokens** | Maximum response length | 4,096 | | **System prompt** | Custom instructions for Sidekick | Platform default | ### Privacy | Setting | Description | Default | |---------|------------|---------| | **Workspace memory** | Allow Sidekick to learn preferences | Enabled | | **Data retention** | How long conversations are stored | 90 days | | **Export data** | Download all workspace data | On demand | ## Danger zone Actions in the danger zone are irreversible: - **Clear workspace memory** — reset Sidekick's learned preferences - **Delete all conversations** — remove conversation history (audit trail preserved) - **Delete workspace** — permanently remove everything > **warning** > Changes to AI behavior settings apply to new conversations only. > Existing conversations retain their original settings. --- ## Notifications Category: Dashboard Guide URL: https://lumenflow.cloud/docs/dashboard-notifications ## Notification channels LumenFlow can notify you through multiple channels: | Channel | Use case | |---------|----------| | **In-app** | Bell icon in the dashboard header | | **Email** | Daily digests or real-time alerts | | **Slack** | Post to a channel when events occur | ## Configurable alerts - **Approval required** — a proposal needs your sign-off - **Approval resolved** — a proposal you're watching was approved or rejected - **Agent stalled** — a session has gone quiet and needs a look - **Reply received** — a channel you're watching got a reply - **Routine completed / failed** — a scheduled routine finished or errored - **Delegated work attention** — delegated work needs your input ## Setting up notifications 1. Go to **Settings → Notifications** 2. Choose a channel for each event type 3. Set frequency (real-time or daily digest) > **info** > Approval notifications are enabled by default. --- ## Search Category: Dashboard Guide URL: https://lumenflow.cloud/docs/dashboard-search ## Global search Press **Ctrl+K** (or **Cmd+K** on Mac) to open the global search overlay from anywhere in the dashboard. ## What you can search | Type | Example query | |------|--------------| | **Conversations** | "Q2 review email" | | **Actions** | "calendar invite sent to design team" | | **Audit entries** | "governance rule modified" | | **Settings** | "billing", "connections", "API keys" | ## Search syntax ### Basic search Type any keyword to search across all content: ``` design team email ``` ### Filtered search Prefix with a type to narrow results: ``` action: calendar invite conversation: budget review audit: governance ``` ### Date-scoped search Add a date qualifier: ``` action: email sent after:2026-01-01 conversation: project update before:2026-02-15 ``` ## Search results Results are ranked by relevance and recency. Click any result to navigate directly to the conversation, action detail, or settings page. > **success** > Search indexes conversations in near real-time. New messages > and actions are searchable within seconds. --- ## Keyboard Shortcuts Category: Dashboard Guide URL: https://lumenflow.cloud/docs/dashboard-keyboard-shortcuts ## Command palette Press **Ctrl+K** (or **Cmd+K**) to open the command palette. Type to search commands, navigate to pages, or trigger actions. ## Global shortcuts | Shortcut | Action | |----------|--------| | `Ctrl+K` | Open command palette / search | | `Ctrl+N` | New conversation | | `Ctrl+,` | Open settings | | `Escape` | Close overlay / panel | ## Sidekick chat shortcuts | Shortcut | Action | |----------|--------| | `Enter` | Send message | | `Shift+Enter` | New line | | `Ctrl+Shift+A` | Approve pending proposal | | `Ctrl+Shift+R` | Reject pending proposal | | `↑` (empty input) | Edit last message | ## Navigation shortcuts | Shortcut | Action | |----------|--------| | `G then H` | Go to Home | | `G then S` | Go to Sidekick | | `G then O` | Go to Observe | | `G then T` | Go to Settings | ## Accessibility All shortcuts can be customized in **Settings → Keyboard Shortcuts**. Screen reader users can press **?** to list all available shortcuts. > **info** > Keyboard shortcuts are disabled when a text input is focused, > except for Ctrl/Cmd combinations. --- ## Governed Work in Flight Category: Dashboard Guide URL: https://lumenflow.cloud/docs/dashboard-delivery ## Where to see work in flight Work is visible in three places: - **Jobs** (`/dashboard//jobs`) — every governed job and what it produced: plans, approvals, outputs, and proof. Open a job for its full detail — steps, agents, connections, approvals, outputs, and proof. - **Operations** (`/dashboard//operations`) — the operator inbox of governed work: agent tasks and their proof of execution, for the person keeping an eye on things. - **The Bridge → Work** (`/dashboard/bridge/work`) — a table of work across the workspaces you belong to, with each work item's status, pull request and available run evidence. ## Pull requests and run evidence When a software delivery job has opened a pull request, its Job detail page shows the stored pull request link in Outputs. It checks the live state through that workspace's GitHub connection. The Bridge work table shows the same link; select **Check state** in the row to read its live state. If the connection is unavailable, the stored link remains usable and the live state is marked unavailable. Where a run disclosed them, both views show gate counts (passed, failed, skipped) and links to its CI run and evidence receipts. These are summary counts and links; they do not imply a gate passed when evidence is absent. ## Job status A job's status reflects where it is in its lifecycle — in progress, waiting on approval, or complete — and rolls up to its Steps, Agents, Connections, Approvals, Outputs, and Proof sections. > **info** > Actions on a job may require approval when the workspace has > approval governance configured — see > [Approval Workflows](/docs/approval-workflows). --- ## Runtime Dashboard Category: Dashboard Guide URL: https://lumenflow.cloud/docs/dashboard-runtime ## Runtime overview The runtime page at `/dashboard/[workspaceId]/observe/runtime` shows hosted agent sessions grouped by workflow status. ## Session groups | Group | Meaning | |-------|---------| | **Active** | Currently executing turns | | **Waiting** | Paused for approval or scheduled wake | | **Resumable** | Suspended, awaiting manual continuation | | **Other** | Completed, errored, or other terminal states | ## Session cards Each session shows: - Session ID with liveness badge (active or stale) - Workflow status badge - Bound work unit (if any) with lane - Pending approval request ID - Next wake timestamp ## Operator controls For eligible sessions, operators can: - **Resume** — continue a suspended session - **Retry** — retry from last checkpoint - **Abort** — terminate immediately Click "Inspect session" to see full workflow state, messages, turn history, and continuation records. --- ## Pipeline Metrics Category: Dashboard Guide URL: https://lumenflow.cloud/docs/dashboard-pipeline ## Pipeline overview Open the workspace overview and select `?panel=pipeline` to see script execution telemetry for the last 7 days. ## What it shows - **Total steps** — script executions in the period - **Distinct scripts** — how many different scripts ran - A list of the most active scripts, each with its run count If nothing has run in the last 7 days, the panel shows an empty state — pipeline activity surfaces here once Sidekick runs delivery scripts. --- ## DORA Metrics Dashboard Category: Dashboard Guide URL: https://lumenflow.cloud/docs/dashboard-dora ## DORA dashboard Open the workspace overview and select `?panel=dora` to see up to four delivery performance metric cards for the last 7 days — typically deployment frequency, lead time, change failure rate, and mean time to recovery, each with its computed value and a tier color. ## Getting started If the panel shows "No delivery health data yet", connect your CI/CD pipeline. Telemetry events are ingested via `POST /api/v1/telemetry` with DORA metric names — see [DORA Metrics](/docs/dora-metrics) for the API contract. --- ## Evidence Chain Traces Category: Dashboard Guide URL: https://lumenflow.cloud/docs/dashboard-traces ## Where trace data lives today There is no dedicated traces dashboard. Open the workspace overview and select `?panel=evidence` for a flat, recent list of evidence-recorded entries (task, timestamp) — for the full span-level DAG, tool calls, policy checks, and evidence receipts behind a task, use the API directly. ## API access List recent traces with `GET /api/v1/traces?days=30`, then fetch one task's full span detail with `GET /api/v1/traces/{taskId}`. See [Traces and Evidence Chains](/docs/traces-and-evidence) for the field reference. --- ## Model Configuration Overview Category: Model Configuration URL: https://lumenflow.cloud/docs/model-config-overview ## Managed first LumenFlow workspaces can start on **managed inference**. That is the default path for trying Sidekick quickly: no provider account, no API keys, and no model routing decisions required up front. ## Bring your own model key When you need a specific provider, a specific model family, or want usage billed directly under your existing provider agreement, you can add a **bring your own model key** (BYOK). | Option | Best for | |--------|----------| | **Managed inference** | Fastest setup, zero-config evaluation, simple operator onboarding | | **BYOK** | Provider choice, direct provider billing, internal model policy requirements | ## How routing works 1. Workspaces can use managed inference immediately when entitled 2. You can add BYOK provider settings in **Settings → Model Configuration** 3. When a BYOK config is present, LumenFlow routes through that provider 4. Billing and usage surfaces still show the governed action and cost outcome ## When to choose BYOK - you need a provider LumenFlow is not hosting for you - you want usage billed directly to OpenAI, Anthropic, or another provider - you have internal policy requirements around approved model vendors > **success** > Your API keys are encrypted at rest with workspace-specific > protection. They are never logged or sent to any service > other than your chosen provider. > See [API Key Management](/docs/model-config-api-keys#rotating-keys) for rotation timing. --- ## Supported Providers Category: Model Configuration URL: https://lumenflow.cloud/docs/model-config-providers ## Supported providers LumenFlow connects to five provider kinds. Each kind has an identifier that the model configuration API uses: | Provider kind | Identifier | |---------------|------------| | OpenAI | `openai` | | Anthropic | `anthropic` | | Google | `google` | | Mistral | `mistral` | | OpenAI-compatible endpoint | `openai-compatible` | The OpenAI-compatible kind takes the base URL of your own endpoint. See [Model configuration](/docs/model-config-api-keys) for how a key and endpoint are declared. ## Models come from the live catalogue Providers change their model lists over time, so this article does not publish a fixed list of models. To see what a key can use now, run model discovery: `POST /api/v1/sidekick/model-config/discovery` asks the provider for its current model list with the key you supply. For OpenRouter, the catalogue and prices come from OpenRouter itself. See [Bring your own key: OpenRouter and free models](/docs/byok-openrouter-and-free-models). ## Choosing a provider Consider these factors: 1. **Task complexity** — advanced reasoning favors larger models 2. **Speed** — smaller models respond faster 3. **Cost** — check your provider's pricing page 4. **Context needs** — long documents need large context windows ## Provider-specific features Some capabilities depend on the provider: - **Vision** — image understanding, on the models that support it. Check the live catalogue. - **Tool use** — function calling for connections (all providers) - **Streaming** — real-time response display (all providers) > **info** > LumenFlow normalizes the API interface across providers. > Switching providers doesn't require any changes to your > conversations or workflows. --- ## API Key Management Category: Model Configuration URL: https://lumenflow.cloud/docs/model-config-api-keys ## Adding an API key 1. Go to **Settings → Model Configuration** 2. Select your provider 3. Paste your API key 4. Click **Save** Saving validates the configuration and stores the encrypted key. A connection probe is a separate provider request; a save does not establish model compatibility or token-count accuracy. ## Declared Messages-protocol endpoints To use your own public HTTPS endpoint that speaks the Messages protocol, register a route through the model-config API with provider `anthropic`, your model identifier, an explicit `baseUrl` and the endpoint's API key. This route accepts a non-empty key of at least 10 characters; without a declared endpoint, the default Anthropic route still requires its normal `sk-ant-` key format. The declared `baseUrl` must include a non-root API path. A bare host or root path is rejected with `400 invalid_request` and `details.fields: ["baseUrl"]`; LumenFlow does not rewrite it. The Messages SDK appends `/messages` to the configured path, so paths such as `/v1`, `/proxy/v1beta` or `/gateway/messages-api` are preserved. Without an explicit `baseUrl`, the default endpoint is unchanged. Only public HTTPS destinations are allowed. Private, loopback and metadata addresses are refused. Changing the endpoint origin requires you to supply the API key again. An endpoint declaration never enables access to a private network. ## Optional per-call admission caps A governed inference caller can send `max_cost_usd` to request pre-call admission against a provider-estimated worst-case charge. It is a positive USD number with at most six fractional digits, within the workspace's resolved registry ceiling, which the platform sets. Scientific notation is accepted only when applying the exponent leaves at most six fractional digits and an exact positive micro-USD amount: `2.49e-4` is accepted, while `1e-7` is refused. Over-precise wire values are refused before number rounding. This is not a promise that the final provider cost stays below the cap. Without the field, existing calls behave as before. The full request contract, streaming and refusals are in [Governed inference API](/docs/governed-inference). Capped calls need an explicit transport profile, even for a native endpoint. Through the model-config API, supply `transportProfile: "anthropic-messages-passthrough"` and `transportProfileAttested: true` together. Setting `transportProfileAttested` attests the configured Messages protocol, exact endpoint, model, API version and output limit, including reasoning. Supply both fields again on every save or key rotation; omitting them clears eligibility. If compromise is suspected, revoke the provider key at the provider too. A provider family, model name or capability declaration alone does not make a route eligible. All authorized model-config PUT saves and rotations commit the configuration and audit together; an audit outage returns `503 audit_unavailable` and leaves the configuration unchanged. Before generation, LumenFlow sends your input to the same endpoint for a token estimate. Counting therefore sends your prompt before admission; its charging and quota terms depend on your endpoint. A successful count is still an estimate, and your attestation does not prove accuracy or count success. Only verified ordinary text and client-function-tool mappings are admitted; unknown shapes, unsupported transports, missing profiles and failed counts refuse. Capped calls are available on supported routes only. The estimated input and the output cap are combined into the admission estimate. Refusals, aborts and timeouts cancel pending work. Your provider's actual BYOK usage and cost remain visible even above the caller cap. ## Key security Your API key is encrypted with industry-standard encryption before storage. The encryption is workspace-specific, so keys cannot be accessed across workspaces. Encryption keys are stored separately from your data, providing multiple layers of protection. ## Rotating keys To rotate your API key: 1. Generate a new key from your provider's dashboard 2. Go to **Settings → Model Configuration** 3. Click **Update Key** 4. Paste the new key 5. Save. New calls use the new key. Calls already selected or running may continue briefly. Revoke the old key at your provider if you need to withdraw its access. ## Declaring token prices The model-config API accepts `declaredPrices` with `inputPerMillion` and `outputPerMillion`, plus optional `cachedInputPerMillion` for cache reads and `cacheWritePerMillion` for cache writes. Rates are USD per million tokens, from 0 to 10000. An omitted cache-read or cache-write rate uses the input rate. These are your own estimates of what your provider charges. The provider bills you directly for model usage. Governed inference reports the declared cost with basis `byok_declared`, and its receipt records cached-input and cache-write token counts. A declared price is not verification of a provider's invoice or compatibility. ## Declaring where your endpoint runs When you connect a custom OpenAI-compatible endpoint you can declare the region it runs in (eu_west, us_east, us_west or apac) under **Endpoint region (declared by you)**. This is your own statement about your endpoint. Keep it accurate. A pinned workspace's model calls compare this declaration with its pinned key region. If no valid endpoint region is declared, the hosted-provider default is used for that comparison; a mismatch is refused before dispatch. Rotating the key keeps the declared region, and changing the provider or the endpoint clears it until you declare it again. For a declared Messages endpoint, set the same `endpointRegion` declaration through the model-config API. The same residency checks apply before any provider request. ## Revoking access If you suspect a key is compromised: 1. Revoke the key at your provider's dashboard immediately 2. Update the key in LumenFlow settings 3. Check the audit trail for unexpected actions ## Model-pinned judgment checks Some governed operations can use a judgment check with a pinned model. A trusted tenant and workspace policy must enable the exact purpose and provider; a purpose mapping or credential alone cannot enable it. The judgment check may use either a managed or an approved workspace BYOK source, so "local" does not guarantee on-device processing. Data is sent only when its purpose, provider and input all permit the request. A timeout, malformed answer, missing serving identity, or different model identity is refused. External providers remain disabled unless the trusted tenant policy explicitly enables them; a platform credential supplies authentication only. > **warning** > Never share your API key in chat messages, emails, or > documentation. LumenFlow will never ask for your key > outside the settings page. --- ## Default Model Settings Category: Model Configuration URL: https://lumenflow.cloud/docs/model-config-defaults ## Default parameters When a new conversation starts, these defaults apply: | Parameter | Description | Range | Default | |-----------|------------|-------|---------| | **Model** | Which LLM to use | Provider-specific | Largest available | | **Temperature** | Response creativity | 0.0–1.0 | 0.7 | | **Max tokens** | Maximum response length | 1–provider max | 4,096 | | **Top P** | Nucleus sampling threshold | 0.0–1.0 | 1.0 | ## System prompt The system prompt sets Sidekick's baseline behavior. The default prompt includes: - Governance awareness (propose before acting) - Workspace context (available connections and tools) - Safety guidelines (escalation triggers) ### Customizing the system prompt You can append custom instructions: ``` Always respond in a professional tone. When drafting emails, use the signature: "Best regards, [Team Name]" Prefer bullet points over paragraphs for summaries. ``` Custom instructions are appended to — not replacing — the platform system prompt. This ensures governance behavior is always present. ## Per-conversation overrides You can override defaults in any conversation by using Sidekick commands: ``` /temperature 0.3 /model gpt-4o-mini ``` Overrides persist for the duration of the conversation and don't affect workspace defaults. > **info** > Lower temperature (0.0–0.3) produces more consistent, factual > responses. Higher temperature (0.7–1.0) produces more creative, > varied output. --- ## Email Automation Category: Use Cases URL: https://lumenflow.cloud/docs/usecase-email-automation ## Overview This walkthrough shows how to use Sidekick with a Gmail connection to automate email workflows with full governance. ## Prerequisites - Gmail connection active in workspace settings - Governance rules configured for email actions ## Scenario: Weekly team update ### Step 1: Create the workflow Tell Sidekick what you want: ``` Every Friday at 4pm, draft a weekly update email to the engineering team summarizing: PRs merged, issues closed, and blockers raised this week. Pull data from our GitHub connection. ``` ### Step 2: Review the proposal Sidekick proposes: 1. Query GitHub for the week's activity 2. Summarize into categories 3. Draft the email 4. Send to engineering@company.com Each step appears as a proposal card in your chat. ### Step 3: Set governance rules For recurring workflows, consider: | Rule | Setting | |------|---------| | GitHub reads | Auto-approve | | Email drafting | Auto-approve | | Email sending | Require approval | This lets Sidekick prepare the email autonomously but wait for your sign-off before sending. ### Step 4: Monitor Ask Sidekick "show me what just ran" each Friday — the Proof widget surfaces the workflow. Approve the final send step, or edit the draft first. > **success** > After a few weeks, if the drafts consistently meet your > standards, you can auto-approve the send step too. --- ## Data Analysis Category: Use Cases URL: https://lumenflow.cloud/docs/usecase-data-analysis ## Overview Sidekick can help you analyze data from connected sources, generate reports, and identify trends — all with governance controls on what data it can access. ## Scenario: Monthly revenue report ### Step 1: Describe the analysis ``` Pull our revenue data for the last month. Break it down by: - Product line - Region - Customer segment Compare to the previous month and highlight significant changes (>10% variance). Format as a summary with a table. ``` ### Step 2: Sidekick's approach Sidekick will propose: 1. Query your connected database for revenue records 2. Aggregate by the requested dimensions 3. Calculate month-over-month changes 4. Generate a formatted summary ### Step 3: Review the output The analysis appears in chat as formatted markdown with tables and highlights. You can: - Ask follow-up questions ("Why did APAC drop 15%?") - Request visualizations ("Show this as a bar chart") - Export the data ("Send this as a CSV to finance@company.com") ## Tips for data analysis 1. **Be specific about dimensions** — "by region" is better than "broken down" 2. **Define thresholds** — "highlight changes over 10%" gives Sidekick clear criteria 3. **Iterate** — start with a broad query and drill down > **info** > Sidekick can only access data through connected services. > It cannot access raw databases unless you've set up a > custom MCP connection. --- ## Team Coordination Category: Use Cases URL: https://lumenflow.cloud/docs/usecase-team-coordination ## Overview Use Sidekick as your team coordination assistant — scheduling meetings, posting updates, and managing follow-ups across Google Calendar and Slack. ## Scenario: Sprint standup automation ### Step 1: Set up the workflow ``` Every weekday at 9:30am: 1. Post a standup prompt to #engineering in Slack asking each team member for: yesterday's progress, today's plan, blockers 2. At 10:00am, collect the responses 3. Summarize into a digest and post to #engineering-leads 4. If anyone mentions a blocker, create a follow-up thread ``` ### Step 2: Required connections | Service | Scopes needed | |---------|--------------| | **Slack** | Read channels, post messages | | **Google Calendar** | Read events (for conflict detection) | ### Step 3: Governance setup | Action | Approval | |--------|----------| | Post standup prompt | Auto-approve | | Read Slack responses | Auto-approve | | Post summary digest | Auto-approve | | Create follow-up threads | Require approval | ### Step 4: Iterate After the first week, review the summaries: - Are they capturing the right information? - Is the formatting clear? - Should any actions be escalated differently? Adjust Sidekick's instructions based on what you learn. > **success** > Team coordination workflows save 30–60 minutes per day > by automating the routine parts of communication. --- ## Customer Support Category: Use Cases URL: https://lumenflow.cloud/docs/usecase-customer-support ## Overview Sidekick can help your support team triage incoming tickets, draft responses, and escalate critical issues — with human review at every step. ## Scenario: Ticket triage and response ### Step 1: Connect your support tool Connect your support platform via custom MCP or webhook integration. Sidekick receives new tickets as they arrive. ### Step 2: Define the triage workflow ``` When a new support ticket arrives: 1. Classify severity (critical, high, medium, low) based on keywords and customer tier 2. For critical tickets: notify #support-urgent in Slack immediately 3. For all tickets: draft a response using our knowledge base 4. Queue the draft for agent review ``` ### Step 3: Governance for support | Action | Approval | |--------|----------| | Read ticket content | Auto-approve | | Classify severity | Auto-approve | | Slack notification (critical) | Auto-approve | | Draft response | Auto-approve | | Send response to customer | Require approval | ### Step 4: Quality monitoring Track these metrics in **Observe → Analytics**: | Metric | Target | |--------|--------| | **First response time** | < 2 hours | | **Draft acceptance rate** | > 80% | | **Escalation accuracy** | > 95% | If draft acceptance drops below 80%, review the rejected drafts and update Sidekick's instructions. > **warning** > Always require human approval before sending responses to > customers. AI-drafted responses should be reviewed for > accuracy and tone. --- ## Integrations Overview Category: Integrations URL: https://lumenflow.cloud/docs/integrations-overview ## Product surfaces LumenFlow currently exposes external integrations through three different product surfaces: | Surface | What it's for | Current examples | |--------|----------------|------------------| | **Tool Connections** | Governed `conn:*` tools inside Sidekick | See Connectors and channels below | | **Channels** | Messaging and inbound/outbound conversation transport | See Connectors and channels below | | **Advanced Custom MCP** | Self-hosted or custom tool servers | Internal tools, niche SaaS, bespoke workflows | ## Connectors and channels Cloud publishes this table from the connector catalogue. It lists every connector and channel that is **Ready** or **Limited**. The catalogue is served at `GET /api/v1/sidekick/catalog`, and `?availability=ready` returns only the ready entries. - **Ready** means the connector is available for general use. - **Limited** means the connector is real and installable, with a deliberately bounded set of governed actions. | Connector | Kind | Availability | |---|---|---| | **Slack** | Channel | Ready | | **Discord** | Channel | Ready | | **Telegram** | Channel | Ready | | **Teams** | Channel | Ready | | **Twilio SMS** | Channel | Ready | | **Custom Webhook** | Channel | Ready | | **WhatsApp** | Channel | Ready | | **Resend** | Channel | Limited | | **Plivo SMS** | Channel | Limited | | **Telnyx SMS** | Channel | Limited | | **Gmail** | Tool connection | Ready | | **Google Calendar** | Tool connection | Ready | | **Google Docs** | Tool connection | Ready | | **Google Sheets** | Tool connection | Ready | | **GitHub** | Tool connection | Ready | | **Vercel** | Tool connection | Ready | | **HubSpot** | Tool connection | Ready | | **Jira** | Tool connection | Ready | | **Notion** | Tool connection | Ready | | **Outlook Mail** | Tool connection | Ready | | **Outlook Calendar** | Tool connection | Ready | | **OneDrive** | Tool connection | Ready | | **Microsoft To Do** | Tool connection | Ready | | **OpenTable** | Tool connection | Limited | | **Yelp** | Tool connection | Limited | | **Greenhouse** | Tool connection | Ready | | **Microsoft Dataverse** | Tool connection | Limited | | **Linear** | Tool connection | Limited | | **Calendly** | Tool connection | Limited | | **Asana** | Tool connection | Limited | | **Salesforce** | Tool connection | Limited | | **Intercom** | Tool connection | Limited | | **Zendesk** | Tool connection | Limited | ## Connection methods Depending on the integration, setup uses one of these methods: | Method | Use case | Setup | |--------|----------|-------| | **OAuth** | Google, Slack, GitHub, HubSpot, Atlassian, Microsoft, Notion | One-click authorize | | **API key** | Greenhouse and some custom services | Paste key in settings | | **MCP** | Advanced custom tools | Deploy or register MCP server | | **Webhooks** | Inbound events and messaging channels | Configure endpoint URL and verification | ## How connections work 1. You add a Tool Connection or channel in **Settings → Connections** 2. LumenFlow securely stores the credentials 3. Sidekick discovers the governed actions available from that integration 4. Governance rules control which actions are allowed ## Reactive routine routing Inbound messages can match configured reactive routines through typed semantic judgment. Provider and channel settings remain eligibility checks. If judgment is disabled, denied, fails, times out, or no active routine can be judged, the message stays review-only with a visible reason; matching a configured keyword alone never starts a routine. Only a successful typed judgment can select an automatic run. ## Connection lifecycle Connections and channels follow a state machine with clear health status: ``` disconnected ──(add integration)──> connected ^ | | (needs config?) | / \ | no yes | | | | v v | inbound_ready action_required | | | | (healthy) (fix config) | | | | v v +──(revoke)──────────── active degraded ``` | State | Meaning | |-------|---------| | **disconnected** | Not configured | | **connected** | Credentials stored, basic outbound works | | **action_required** | Needs additional setup (webhook URL, bot token, etc.) | | **inbound_ready** | Full bidirectional capability | | **degraded** | Was working, now failing (token expired, webhook down) | OAuth tokens are refreshed automatically. You can revoke access at any time from settings. For newer integrations, `v1` means the integration is real and installable today, but intentionally bounded. LumenFlow exposes the most useful governed actions first and expands later instead of claiming the provider's full API on day one. ## Security - OAuth tokens are encrypted at rest - Credentials are never exposed in the UI after initial setup - All connection activity appears in the audit trail - Revoking a connection immediately stops all related actions > **info** > LumenFlow requests minimal scopes by default. You choose > exactly which permissions to grant during OAuth authorization. --- ## Google Workspace Category: Integrations URL: https://lumenflow.cloud/docs/integrations-google-workspace ## Available scopes | Service | Capabilities | |---------|-------------| | **Gmail** | Read, draft, send, and label emails | | **Calendar** | Read, create, modify, and delete events | | **Google Docs** | Search documents, summarize content, and append bounded updates | | **Google Sheets** | Search spreadsheets, summarize tabs, and append bounded rows | ## Setup 1. Go to **Settings → Connections** 2. Click **Add Connection → Google Workspace** 3. Sign in with your Google account 4. Select which scopes to authorize 5. Click **Allow** ## Gmail actions Sidekick can: - **Read emails** — search by subject, sender, date, or label - **Draft emails** — compose with subject, body, recipients, and attachments - **Send emails** — deliver drafted emails (governance-controlled) - **Label emails** — organize with labels and filters ## Calendar actions Sidekick can: - **Read events** — list upcoming meetings, check availability - **Create events** — schedule meetings with attendees and details - **Modify events** — reschedule, add attendees, update descriptions - **Cancel events** — remove events and notify attendees ## Docs and Sheets actions Sidekick can: - **Search documents and spreadsheets** — find shared artifacts relevant to the current task - **Summarize content** — review Google Docs or Sheets without leaving Sidekick - **Append bounded updates** — add notes to a doc or append rows to a sheet when governance allows it This is a bounded v1 surface focused on common day-to-day work, not the full Google Workspace API. > **warning** > Grant only the scopes you need. You can always add more > scopes later by re-authorizing the connection. --- ## Slack Category: Integrations URL: https://lumenflow.cloud/docs/integrations-slack > **info** > Governed sends and provider read access work today. Automatic inbound > chat depends on completing the Slack Events API ingress checklist for > your workspace. ## Available today | Action | Description | |--------|------------| | **Post message** | Send to any channel Sidekick is invited to | | **Read channel** | Read recent messages from a channel | | **Thread reply** | Reply into existing Slack threads | | **Notifications** | Use Slack for approvals, alerts, and routed updates | ## Inbound chat rollout Inbound Slack chat is available after the workspace admin completes the provider-side checklist: 1. Connect the Slack workspace token 2. Save the Slack signing secret 3. Point the Events API to the LumenFlow-issued inbound endpoint 4. Verify the target before enabling production automation ## Setup 1. Go to **Settings → Connections** 2. Click **Add Connection → Slack** 3. Connect the Slack workspace you want Sidekick to use 4. Confirm the team metadata and required scopes 5. Save inbound verification settings if you want automatic chat ingress ## Channel access Sidekick can only access channels it's been invited to. To add access to a new channel: 1. Invite Sidekick to the channel in Slack (`/invite @LumenFlow`) 2. The channel appears in LumenFlow automatically ## Best practices - **Use dedicated channels** — create channels like #sidekick-updates for automated posts - **Set governance rules** — require approval for messages to high-visibility channels - **Use threads** — configure Sidekick to reply in threads to avoid channel noise ## Message formatting Sidekick formats Slack messages using Slack's standard markdown syntax, including bold, italic, inline code, and blockquotes. > **info** > Slack messages sent by Sidekick appear as the LumenFlow bot. > Recipients can see which workspace triggered the message, and the > resulting action stays visible in LumenFlow's proof trail. --- ## GitHub Category: Integrations URL: https://lumenflow.cloud/docs/integrations-github ## Available today | Action | Description | |--------|------------| | **Summarize repository work** | Review active issues, pull requests, and recent repository state | | **Inspect pull requests** | Read pull request details, review state, and changed files | | **Manage issues** | Create issues and update existing tracked work | ## Setup 1. Go to **Settings → Connections** 2. Click **Add Connection → GitHub** 3. Authorize LumenFlow on your GitHub account or organization 4. Confirm the repositories and scopes you want the workspace to use ## Use cases ### Code review summaries ``` Summarize the open PRs in our main repo. For each PR, list: the author, files changed, and current review status. ``` ### Issue triage ``` Find all issues labeled "bug" that were opened this week. Categorize by component and suggest priority levels. ``` ### Release notes ``` Generate release notes from all merged PRs since the last tagged release. Group by feature, fix, and chore. ``` ## Capability boundary GitHub ships as a real v1 connector. That means the integration is available now, but intentionally focused on the most useful governed repository and issue workflows first. ## Governance considerations | Action | Recommended approval | |--------|---------------------| | Read repositories | Auto-approve | | Read issues / PRs | Auto-approve | | Comment on issues | Require approval | | Create issues | Require approval | > **info** > Read access is the safest default. Keep issue creation and updates > behind approval unless your workspace already has clear governance > rules for GitHub changes. --- ## Jira Category: Integrations URL: https://lumenflow.cloud/docs/integrations-jira ## Available today | Action | Description | |--------|------------| | **Find matching issues** | Search Jira Cloud work using governed connector access | | **Summarize issue state** | Review ticket details, comments, and current status | | **Create issues** | Open new tracked work from Sidekick | | **Comment on issues** | Add bounded updates to existing tickets | ## Setup 1. Go to **Settings → Connections** 2. Click **Add Connection → Jira** 3. Authorize through Atlassian OAuth 4. Confirm the Jira Cloud site and scopes the workspace should use ## How to use it Ask for the work you need in plain language: ``` Show me all high-priority bugs assigned to the backend team that haven't been updated in the last 7 days. ``` ## Sprint reporting Ask Sidekick for sprint summaries: ``` Summarize the current sprint: story points completed vs committed, unfinished items, and any scope changes since sprint start. ``` ## Capability boundary Jira ships today as a bounded Jira Cloud v1 connector. For Jira Data Center or custom internal Jira workflows, use an Advanced Custom MCP server instead of expecting the built-in connector to cover every case. ## Governance | Action | Recommended approval | |--------|---------------------| | Read issues | Auto-approve | | Read sprints | Auto-approve | | Create issues | Require approval | | Update issues | Require approval | > **info** > The built-in connector targets Jira Cloud. Use Advanced Custom MCP > when you need Data Center support or a more specialized Jira surface. --- ## Notion Category: Integrations URL: https://lumenflow.cloud/docs/integrations-notion ## Capabilities | Action | Description | |--------|------------| | **Find pages** | Search shared Notion pages relevant to the current task | | **Read docs** | Summarize page content inside Sidekick | | **Update notes** | Make bounded updates to shared notes when governance allows it | ## Setup 1. Go to **Settings → Connections** 2. Click **Add Connection → Notion** 3. Authorize LumenFlow in Notion 4. Select which pages or team spaces to share ## Use cases ### Knowledge base queries ``` Search our Notion wiki for the onboarding checklist and summarize the steps for new engineers. ``` ### Working notes updates ``` Find the project note for the API migration and append a short status update with the blockers we discussed today. ``` ### Documentation reference When drafting emails or Slack messages, Sidekick can reference Notion pages for accuracy: ``` Draft a response to the client's question about our SLA terms. Reference our SLA page in Notion for the exact numbers. ``` ## Capability boundary Notion ships as a real v1 connector focused on the common "find, read, and update notes" workflow. It does not claim the full Notion API surface inside Sidekick. ## Access control Notion controls which pages LumenFlow can see. To grant access to additional pages: 1. Open the page in Notion 2. Click **Share** then **Invite** 3. Add the LumenFlow integration > **warning** > Notion pages shared with LumenFlow are accessible to all > members of the workspace. Be mindful of sensitive content. --- ## Zapier Category: Integrations URL: https://lumenflow.cloud/docs/integrations-zapier ## Status: no native Zapier connector LumenFlow has no dedicated Zapier entry under workspace connections and no one-click authorization flow. This article describes the path that works right now. ## What works today: the MCP host LumenFlow exposes a workspace-scoped MCP (Model Context Protocol) endpoint that any MCP-compatible client can call, authenticated with a workspace API key: ``` POST https:///api/v1/mcp Authorization: Bearer ``` Generate an API key from your workspace settings — see [API reference](/docs/api-reference). One tool is wired up today: a read-only list of your workspace's delivery programs, each with its ID, title, status, created and completed dates, and a progress figure. It never makes changes to your workspace. See [Connect to LumenFlow via MCP](/docs/mcp-server-connection) for the full endpoint and authentication details. If your automation platform can act as an MCP client, point it at this endpoint to read delivery-program data into a workflow. --- ## Webhooks Category: Integrations URL: https://lumenflow.cloud/docs/integrations-webhooks ## Outbound workspace webhooks LumenFlow can POST signed workspace events to an HTTPS endpoint you register. This is the Settings → Connections → Webhooks flow — not a separate incoming-webhook URL surface. ### Configure a subscription 1. Go to **Settings → Connections → Webhooks** 2. Click **Add Webhook** 3. Enter a public HTTPS destination URL 4. Save — LumenFlow generates a signing secret and shows it once Store the signing secret immediately. It cannot be retrieved again; delete and recreate the subscription to rotate it. v1 delivers the `tool_invocation` event kind (workspace tool runs recorded in the action log). Each event is delivered at most once on success, with retry on transient failures. ### Test delivery Use **Send test** on a subscription card to POST a synthetic signed event through the same delivery path the worker uses. A successful test reaches your endpoint with a valid signature. ### Destination rules (egress) Destinations must be **HTTPS** and resolve to a public address. Loopback (`127.0.0.1`, `localhost`) and private-network targets are refused at create/edit time and again at delivery time — they never enter the retry loop. ### Event payload Each delivery is a JSON envelope: - `delivery_id` — stable id for this delivery chain - `workspace_id` — your workspace - `occurred_at` — delivery timestamp (ISO-8601) - `events[]` — one or more events with `id`, `kind`, `occurredAt`, and `data` ### Webhook signing Every delivery includes: - `X-Lumenflow-Signature: sha256=` — HMAC-SHA256, using your subscription secret, of `.` - `X-Lumenflow-Delivery-Id` — the envelope `delivery_id` - `X-Lumenflow-Timestamp` — unix seconds used when signing To verify a delivery, join the `X-Lumenflow-Timestamp` value, a dot and the raw request body. Compute HMAC-SHA256 of that string with your secret, and compare the hex digest with the value after `sha256=` in constant time. Reject any delivery whose timestamp is more than five minutes from your clock. That window is the replay guard. Verify the signature before you trust the payload. ### Signature schemes by surface | Surface | Header value | Signed input | Versioned | |---------|--------------|--------------|-----------| | Workspace webhooks | `sha256=` | `.` | No | | Job result callbacks | `t=,v1=` | `.`, keyed with the callback secret | Yes, `v1` | Engagement subscriptions use the same `sha256=` form as workspace webhooks. Job result callbacks are described in the Jobs lifecycle article in the Developer Guide. --- ## Custom MCP Servers Category: Integrations URL: https://lumenflow.cloud/docs/integrations-custom-mcp ## What is MCP? The **Model Context Protocol** (MCP) is an open standard for connecting AI assistants to external tools and data sources. LumenFlow supports MCP natively. ## Building an MCP server An MCP server exposes tools with names, descriptions, and input schemas. When connected, LumenFlow automatically discovers these tools and makes them available to Sidekick. MCP servers can be written in any language that supports MCP. Cloud-hosted connections use public HTTPS. For details on building MCP servers, see the [MCP specification](https://modelcontextprotocol.io). ## Connecting your server 1. Deploy your MCP server at a public HTTPS URL. Cloud connects only to public HTTPS endpoints. The URL must not contain credentials, a query string, or a fragment. A stdio or loopback server runs through a connected runner, not on Cloud. 2. Go to **Settings → Connections → Custom MCP** 3. Enter the server URL 4. LumenFlow discovers available tools automatically 5. Configure governance rules for each tool ## Tool discovery When you connect an MCP server, LumenFlow queries it for available tools and their schemas. These appear in Sidekick's tool palette and can be used in conversations. ## Per-user OAuth Some hosted MCP servers need each person to sign in with their own account. For these, the server uses OAuth 2.1 and each workspace member connects their own account: - LumenFlow reads the server's authorization metadata and requires PKCE with the `S256` method. - Where the server uses dynamic client registration, LumenFlow registers a client and stores it. - The authorization request names the server URL as the resource indicator (RFC 8707), so a token is only used for that server. - Each token belongs to one member. Disconnecting removes that member's token and leaves other members' connections in place. Members connect and disconnect from the dashboard. ## Remote MCP directory The directory lists remote MCP servers that LumenFlow has checked. It is a list of suggestions. Connecting one creates a workspace custom MCP server through the same path as a manual add. The new server is disabled until it passes admission, and its tools follow the read-only rules below. Templates are shown only while their last re-check passes. ## Read-only tools A tool from an admitted server is treated as read-only only when its declared manifest marks it read-only. Every other tool is treated as consequential and goes through your governance rules. ## Best practices - **Validate inputs** — MCP tools receive user-influenced input - **Return structured data** — JSON responses work best - **Handle errors gracefully** — return error messages, not stack traces - **Document tools** — clear descriptions help Sidekick use them correctly > **success** > MCP servers can be written in any language. The protocol > uses JSON-RPC. Cloud-hosted connections use public HTTPS. --- ## Microsoft Teams Category: Integrations URL: https://lumenflow.cloud/docs/integrations-teams ## What you can do Connect a Microsoft Teams bot to your LumenFlow workspace so Sidekick can post messages into Teams channels and conversations, and receive inbound messages from your team members. | Action | Description | Status | |--------|------------|--------| | **Send message** | Post to any Teams channel or conversation | Shipped | | **Reply to thread** | Reply to an existing activity by id | Shipped | | **Receive messages** | Ingest inbound messages via Bot Framework webhook | Shipped | | **Approval routing** | Route outbound messages through approval workflow | Shipped | ## Setup 1. **Register a Bot** in the [Azure Bot Service](https://portal.azure.com). You need a **Bot App ID** and a **Bot App Password** (client secret). 2. Go to **Settings > Connections** in LumenFlow 3. Click **Add Connection > Microsoft Teams** 4. Enter your **Bot App ID** and **Bot App Password** 5. Optionally enter a **Tenant ID** to restrict to a single Azure AD tenant 6. Click **Save** -- LumenFlow encrypts your credentials and returns a webhook URL > **info** > LumenFlow generates a unique webhook URL for your workspace. > You will configure this URL as the Bot Framework messaging endpoint > in the Azure portal. ## Webhook setup After saving the connection, LumenFlow returns a webhook URL in the format: ``` https://your-domain.com/api/v1/sidekick/integrations/teams/webhook?key= ``` 1. Open the Azure Bot Service configuration for your bot 2. Set the **Messaging endpoint** to the webhook URL above 3. Send a test message to the bot in Teams -- it should appear in LumenFlow's activity feed ## Security - **Bot Framework JWT verification** -- every inbound webhook request is verified against Microsoft's Bot Framework OpenID metadata. Invalid tokens are rejected with HTTP 401. - **Webhook key** -- the `?key=` parameter uniquely identifies your workspace integration. Keep it private. - **Rate limiting** -- distributed rate limits protect against webhook flooding (per-integration and per-workspace). - **Credentials encrypted at rest** -- your Bot App Password is encrypted before storage. ## Best practices - **Dedicate a bot per workspace** -- avoid sharing a single bot registration across multiple LumenFlow workspaces - **Use tenant scoping** -- pass your Azure AD Tenant ID during setup to restrict the bot to your organization - **Set governance rules** -- require approval for messages posted to high-visibility channels > **info** > Inbound messages trigger Sidekick's chat pipeline automatically. > Responses follow your workspace's governance rules before being > sent back to Teams. --- ## Discord Category: Integrations URL: https://lumenflow.cloud/docs/integrations-discord ## What you can do Connect a Discord bot to your LumenFlow workspace. Sidekick can post messages to Discord channels and threads, and receive inbound messages via the bridge ingest endpoint. | Action | Description | Status | |--------|------------|--------| | **Send message** | Post to any Discord channel the bot can access | Shipped | | **Reply to message** | Reply to a specific message by id | Shipped | | **Receive messages** | Ingest inbound events via signed bridge webhook | Shipped | | **Bot identity check** | Validates bot token against Discord API on setup | Shipped | | **Approval routing** | Route outbound messages through approval workflow | Shipped | ## Setup 1. **Create a Discord Application** at the [Discord Developer Portal](https://discord.com/developers/applications) 2. Create a **Bot** user and copy the **Bot Token** 3. Invite the bot to your Discord server with appropriate permissions (Send Messages, Read Message History) 4. Go to **Settings > Connections** in LumenFlow 5. Click **Add Connection > Discord** 6. Enter the **Bot Token** and optionally a default channel 7. Click **Save** -- LumenFlow validates the token against the Discord API and stores it encrypted > **warning** > If this Discord bot token is already connected to a different > LumenFlow workspace, the install will be rejected. One bot per > workspace prevents message routing conflicts. ## Bridge ingest Discord does not natively push events to a webhook URL the way Slack or Teams do. LumenFlow provides a **bridge runtime** that connects to Discord's Gateway and forwards events to the ingest endpoint. The ingest endpoint uses HMAC signature verification: - `x-sidekick-signature` -- HMAC-SHA256 of the request body - `x-sidekick-timestamp` -- ISO 8601 timestamp for replay protection > **info** > The bridge runtime name and registration metadata are stored > automatically during setup. Check the onboarding status panel for > bridge health. ## Security - **Bot token validated on save** -- LumenFlow calls Discord's `/users/@me` endpoint to verify the token before storing it - **HMAC ingest signature** -- inbound events are signed with an encrypted shared secret - **Rate limiting** -- distributed per-integration and per-workspace limits - **Scoped permissions** -- only `messages.write`, `channels.read`, and `messages.read` scopes are accepted ## Disconnecting To remove the integration, go to **Settings > Connections > Discord** and click **Disconnect**. This removes stored credentials from LumenFlow but does not delete the bot from your Discord server. --- ## Telegram Category: Integrations URL: https://lumenflow.cloud/docs/integrations-telegram ## What you can do Connect a Telegram bot to your LumenFlow workspace. Sidekick can send messages to Telegram chats and groups, and automatically receive inbound messages via Telegram's native webhook system. | Action | Description | Status | |--------|------------|--------| | **Send message** | Send to any Telegram chat the bot is in | Shipped | | **Receive messages** | Automatic webhook registration with Telegram | Shipped | | **Bot validation** | Verifies bot token via Telegram `getMe` API | Shipped | | **Approval routing** | Route outbound messages through approval workflow | Shipped | ## Setup 1. **Create a Telegram bot** by talking to [@BotFather](https://t.me/BotFather) and copying the **Bot Token** 2. Go to **Settings > Connections** in LumenFlow 3. Click **Add Connection > Telegram** 4. Enter the **Bot Token** 5. Click **Save** LumenFlow will: - Call Telegram's `getMe` to verify the bot identity - Call `setWebhook` to register a unique inbound URL with Telegram - Generate and store an encrypted webhook secret token > **info** > Unlike most integrations, Telegram webhook registration is fully > automatic. You do not need to configure any URLs manually. ## How the webhook works LumenFlow registers a webhook URL with Telegram in the format: ``` https://your-domain.com/api/v1/sidekick/integrations/telegram/webhook?key= ``` Telegram delivers updates to this URL. LumenFlow verifies each request using the `X-Telegram-Bot-Api-Secret-Token` header, which Telegram sets automatically when a secret token is provided during webhook registration. ## Security - **Bot identity verified** -- the `getMe` call confirms the token is valid before any data is stored - **Exclusive bot** -- a Telegram bot cannot be connected to two LumenFlow workspaces at the same time - **Secret token verification** -- every inbound webhook is verified using a secret token that Telegram signs into each delivery - **Rate limiting** -- distributed limits protect against webhook flooding - **Credentials encrypted at rest** -- the bot token is encrypted before storage ## Disconnecting When you disconnect the Telegram integration, LumenFlow calls Telegram's `deleteWebhook` API to unregister the inbound URL, then removes stored credentials. > **warning** > If the bot token has been rotated or revoked, LumenFlow may not > be able to clean up the remote webhook. You can remove it manually > by calling `/deleteWebhook` via BotFather. --- ## Twilio SMS Category: Integrations URL: https://lumenflow.cloud/docs/integrations-twilio ## What you can do Connect a Twilio phone number to your LumenFlow workspace. Sidekick can send SMS messages to any phone number and receive inbound texts via Twilio's webhook system. | Action | Description | Status | |--------|------------|--------| | **Send SMS** | Send a text message to any phone number | Shipped | | **Receive SMS** | Ingest inbound texts via Twilio webhook | Shipped | | **Approval routing** | Route outbound SMS through approval workflow | Shipped | | **TwiML response** | Returns empty TwiML to acknowledge receipt | Shipped | ## Setup 1. **Get your Twilio credentials** from the [Twilio Console](https://console.twilio.com): - **Account SID** - **Auth Token** - **Phone Number** (the Twilio number you want to send from) 2. Go to **Settings > Connections** in LumenFlow 3. Click **Add Connection > Twilio SMS** 4. Enter your **Account SID**, **Auth Token**, and **Phone Number** 5. Click **Save** -- LumenFlow encrypts your auth token and returns a webhook URL ## Webhook setup After saving, configure your Twilio phone number to forward inbound SMS to the LumenFlow webhook: 1. Open the [Twilio Console](https://console.twilio.com) > Phone Numbers > Manage > Active Numbers 2. Select the phone number you configured 3. Under **Messaging > A message comes in**, set the webhook to: ``` https://your-domain.com/api/v1/sidekick/integrations/twilio/webhook?key= ``` 4. Set the HTTP method to **POST** 5. Save the configuration > **info** > LumenFlow responds with an empty TwiML `` > to acknowledge receipt. Sidekick replies are sent as separate > outbound API calls, not inline TwiML. ## Security - **Twilio signature verification** -- every inbound webhook is verified using the `X-Twilio-Signature` header and your Auth Token, following Twilio's standard HMAC-SHA1 signature scheme - **Rate limiting** -- distributed per-integration and per-workspace limits - **Credentials encrypted at rest** -- your Auth Token is encrypted before storage - **Verification metadata** -- LumenFlow records when the last successful signature verification occurred, visible in the connection status panel ## Best practices - **Use a dedicated phone number** -- avoid sharing the number with other services to prevent webhook conflicts - **Set governance rules** -- require approval for SMS to external numbers outside your organization - **Monitor delivery** -- check the activity feed for send failures and webhook verification errors --- ## WhatsApp Category: Integrations URL: https://lumenflow.cloud/docs/integrations-whatsapp ## What you can do Connect a WhatsApp Business phone number to your LumenFlow workspace. Sidekick can send messages (including template messages), manage approved templates, and receive inbound WhatsApp messages. | Action | Description | Status | |--------|------------|--------| | **Send message** | Send text messages to WhatsApp users | Shipped | | **Send template** | Send pre-approved template messages with parameters | Shipped | | **List templates** | View synced approved templates from your WABA | Shipped | | **Receive messages** | Ingest inbound messages via Meta webhook | Shipped | | **Webhook verification** | Handle Meta's hub.verify challenge | Shipped | | **Approval routing** | Route outbound messages through approval workflow | Shipped | ## Setup 1. **Get your WhatsApp Business credentials** from the [Meta Business Suite](https://business.facebook.com): - **Permanent Access Token** (System User token with `whatsapp_business_messaging` permission) - **Phone Number ID** - **WhatsApp Business Account (WABA) ID** - **App Secret** (from your Meta App settings) 2. Go to **Settings > Connections** in LumenFlow 3. Click **Add Connection > WhatsApp** 4. Enter all four credentials 5. Click **Save** LumenFlow will: - Validate the phone number against the WhatsApp Cloud API - Sync your approved message templates - Generate a unique webhook URL and verify token > **warning** > Use a **permanent** System User token, not a temporary token from > the API Setup page. Temporary tokens expire after 24 hours and will > break the integration. ## Webhook setup After saving, register the webhook in Meta's App Dashboard: 1. Open the [Meta App Dashboard](https://developers.facebook.com/apps) 2. Go to **WhatsApp > Configuration > Webhook** 3. Set the **Callback URL** to: ``` https://your-domain.com/api/v1/sidekick/integrations/whatsapp/webhook?key= ``` 4. Set the **Verify Token** to the value shown in LumenFlow's connection status panel 5. Click **Verify and Save** 6. Subscribe to the `messages` webhook field > **info** > LumenFlow handles the Meta verification challenge automatically. > When Meta sends the `hub.verify_token` challenge, LumenFlow > responds with the `hub.challenge` value if the token matches. ## Template messages WhatsApp requires pre-approved templates for initiating conversations outside the 24-hour customer service window. LumenFlow syncs your approved templates during setup. To send a template message, include the template name, language code, and any parameters in your send request. Templates are listed at **Settings > Connections > WhatsApp > Templates**. ## Security - **Phone number validation** -- the WhatsApp Cloud API is called during setup to verify the phone number id is accessible - **Meta signature verification** -- every inbound webhook is verified using the `X-Hub-Signature-256` header and your App Secret, following Meta's standard HMAC-SHA256 scheme - **Rate limiting** -- distributed per-integration and per-workspace limits - **Credentials encrypted at rest** -- your access token and app secret are encrypted before storage ## Disconnecting To remove the integration, go to **Settings > Connections > WhatsApp** and click **Disconnect**. Remember to also remove the webhook subscription in the Meta App Dashboard. --- ## Custom Webhooks Category: Integrations URL: https://lumenflow.cloud/docs/integrations-custom-webhooks ## What you can do The custom webhook integration lets you connect LumenFlow to any external system that can send or receive HTTP requests. Unlike the built-in channel integrations (Slack, Teams, Discord), custom webhooks give you full control over the payload format and authentication. | Action | Description | Status | |--------|------------|--------| | **Send outbound** | POST/PUT/PATCH to any external URL | Shipped | | **Receive inbound** | Accept signed webhook events from external systems | Shipped | | **Custom body template** | Define the outbound payload structure | Shipped | | **Flexible field mapping** | Map inbound fields for event id, channel, timestamp | Shipped | | **Approval routing** | Route outbound calls through approval workflow | Shipped | ## Setup 1. Go to **Settings > Connections** in LumenFlow 2. Click **Add Connection > Custom Webhook** 3. Enter the required fields: - **Outbound URL** -- where LumenFlow sends events - **Shared Secret** -- used for HMAC signature verification 4. Optionally configure: - **Default channel** -- fallback channel name for routing - **Outbound HTTP method** -- POST (default), PUT, or PATCH - **Auth header name** -- custom authorization header - **Body template** -- custom JSON template for outbound payloads 5. Click **Save** ## Inbound webhook After saving, LumenFlow generates a unique inbound endpoint: ``` https://your-domain.com/api/v1/sidekick/integrations/webhook?key= ``` External systems POST JSON to this URL. LumenFlow verifies the HMAC signature and ingests the event into Sidekick's channel inbox. ### Required headers | Header | Description | |--------|------------| | `x-sidekick-signature` | HMAC-SHA256 signature of the request body | | `x-sidekick-timestamp` | ISO 8601 timestamp for replay protection | ### Inbound payload fields LumenFlow extracts event data from these JSON fields (configurable): | Field | Default key | Description | |-------|------------|------------| | Event ID | `event_id` | Unique event identifier (falls back to SHA-256 hash) | | Channel | `channel` | Routing channel (falls back to default channel) | | Message ID | `message_id` | External message identifier | | Timestamp | `event_ts` | Event timestamp (ISO 8601 or Unix epoch) | | User text | `text`, `message`, `content`, or `body` | Message content for chat processing | ## Security - **HMAC signature verification** -- every inbound request is verified against the shared secret using SHA-256 - **Timestamp replay protection** -- stale timestamps are rejected - **URL safety validation** -- outbound URLs are checked against SSRF protections before saving - **Rate limiting** -- distributed per-integration and per-workspace limits - **Credentials encrypted at rest** -- the shared secret is encrypted before storage ## Use cases - **CRM notifications** -- receive deal updates from your CRM - **Alerting** -- push alerts to an internal dashboard or tool - **Custom bots** -- wire up any chat system not natively supported - **CI/CD** -- receive build and deploy notifications > **info** > Custom webhooks support bidirectional communication. Use outbound > webhooks to push data to external systems, and the inbound endpoint > to receive events back. Both directions are governed by your > workspace's approval rules. --- ## Public Q&A Widget Category: Integrations URL: https://lumenflow.cloud/docs/integrations-public-chat ## What you can do The public Q&A widget provides a chat interface for website visitors to ask questions about your product. It uses LumenFlow's knowledge corpus and hybrid retrieval to generate accurate, grounded answers without requiring authentication. | Capability | Description | Status | |------------|------------|--------| | **Streaming chat** | Real-time SSE streaming responses | Shipped | | **Hybrid retrieval** | Combines corpus knowledge with semantic search | Shipped | | **Rate limiting** | Per-client rate limiting | Shipped | | **Abuse controls** | Message length limits, conversation cap, payload size | Shipped | | **Analytics** | Aggregate metrics (no transcript storage) | Shipped | ## How it works The public chat endpoint streams AI responses grounded in your knowledge corpus. When a visitor asks a question: 1. The message is validated for length, payload size, and abuse 2. Rate limits are checked (per client) 3. Relevant knowledge is retrieved using hybrid search (keyword + semantic) 4. The AI generates a streaming response grounded in the retrieved context 5. Aggregate analytics are emitted (topics, turn count, message length bucket) > **info** > The public chat does not store conversation transcripts. Only > aggregate analytics (topic distribution, turn counts, rate limit > events) are logged. ## Limits - **Conversation turns** -- maximum 10 turns per conversation - **Message length** -- enforced server-side per message - **Payload size** -- request body size capped for abuse prevention - **Rate limiting** -- per client: a per-minute burst limit **plus a per-visitor daily ceiling** so a single source can't drive unbounded usage over a day ## Knowledge corpus The widget draws answers from the public knowledge corpus built into LumenFlow. This includes product documentation, feature descriptions, and frequently asked questions. ## Embedding the widget The public chat endpoint is available at: ``` POST /api/public/sidekick/chat ``` Send a JSON body with a `messages` array following the standard chat message format. The response is an SSE stream compatible with the Vercel AI SDK `useChat` hook. --- ## Client Engagement Chat Category: Integrations URL: https://lumenflow.cloud/docs/integrations-client-chat ## What you can do The client engagement chat provides a private, branded chat portal for individual clients. Each client gets a dedicated endpoint that draws on client-specific knowledge documents, with answers grounded in engagement materials relevant to that client. | Capability | Description | Status | |------------|------------|--------| | **Per-client portal** | Unique URL per client slug | Shipped | | **Engagement-scoped grounding** | Documents sourced from the engagement projection read-model | Shipped | | **Engagement token auth** | Bearer-token validation via the engagement projection API | Shipped | | **Streaming chat** | Real-time SSE streaming responses | Shipped | | **Conversation limits** | Turn cap and message length validation | Shipped | | **Default-deny visibility** | Visibility policy inherited from the engagement projection | Shipped | ## How it works Each client portal is accessed via a unique URL: ``` POST /api/clients//chat Authorization: Bearer ``` When a user sends a message: 1. The engagement-scoped token is verified through the engagement projection API — the same auth path external integrations use. 2. The engagement is loaded with its enabled capabilities and audience scope. 3. Grounding documents are pulled from the engagement document read-model. 4. The AI generates a streaming response grounded in the trusted engagement materials returned by the projection. ## Knowledge sources Grounding documents come from the engagement projection's document read-model. Workspace integrators publish documents to the engagement index; the chat surface inherits the same default-deny visibility the static `/clients/{slug}` projection applies. ## Configuration | Variable | Description | |----------|------------| | Engagement token | Issued per engagement via the projection API; presented as `Authorization: Bearer` | ## Limits - **Conversation turns** -- maximum 10 turns per session - **Message length** -- 2,000 characters per message - **Retrieval results** -- bounded by the engagement document read model ## Security - **Engagement-scoped auth** -- every request requires a valid engagement token; workspace API keys and shared environment tokens are no longer accepted. - **Client isolation** -- each engagement slug resolves to its own projection scope; visibility policy is enforced by the loader. - **Default-deny visibility** -- the chat surface never sees content the static projection would have redacted. > **warning** > Engagement tokens are per-engagement credentials. Treat them > like API keys and rotate via the engagement token management > surface if they may have been exposed. --- ## What Are Governance Bridges? Category: Governance & Policy URL: https://lumenflow.cloud/docs/bridges-overview ## The trust gap When you adopt AI automation, there's a gap between what the AI can do and what your organization trusts it to do. Governance bridges close that gap. ## What is a governance bridge? A governance bridge is a set of rules, approvals, and audit mechanisms that connect AI capabilities to your organization's existing approval culture. Think of it as a filter between what AI *can* do and what it *may* do — with rules, approvals, and an audit trail at every step. ## Why bridges matter Without governance: - AI actions are opaque — you don't know what happened or why - Mistakes are invisible until they cause damage - Compliance teams can't audit AI-driven decisions - Teams don't trust the AI and underutilize it With governance bridges: - Every action is proposed, reviewed, and logged - You control the autonomy level for each action type - Full audit trail satisfies compliance requirements - Trust grows incrementally as the AI proves reliable ## Bridge components | Component | Purpose | |-----------|---------| | **Rules** | Define what's auto-approved vs. needs review | | **Approvals** | Route actions to the right decision-maker | | **Cost controls** | Prevent runaway spending | | **Audit trail** | Record every decision for compliance | | **Role permissions** | Control who can modify governance settings | --- ## Agent Telemetry & Governance Evidence Category: Governance & Policy URL: https://lumenflow.cloud/docs/agent-telemetry-and-governance-evidence ## What LumenFlow sees once a runtime is connected Connect any LumenFlow-governed runtime to your workspace and the control plane captures the **full activity surface** of your agents — not just a slice. This works for any client, model, or BYOK setup: the signal rides your everyday commands, so it does not depend on a particular vendor's hooks. Captured streams include: - **Tool activity** — which tools agents invoked, with status and timing - **Lane signals** and **workflow progress** - **Model/classification activity** and **methodology** signals - **Prompt quality** checks - **Incidents** — failures and their context ## Governance evidence Beyond activity, LumenFlow records **governance evidence** as first-class, tamper-evident audit facts: - **Force-bypass events** — when someone overrode a guardrail, with who, when, on which branch, and why - **Skipped-gate events** — when quality gates were skipped, with the reason, the work unit, and any follow-up reference This is the evidence an auditor or a security review asks for: not "trust us," but a queryable record of every override and every skip. ## Emission coverage For each workspace you can see **whether a connected client is actually emitting** — so you can tell the difference between: - a client that is **fully connected and reporting**, - one that is **connected but not yet upgraded** (emitting only part of the surface), and - one that is **emitting nothing**. No more guessing whether silence means "all clear" or "not wired up." ## Privacy by default Sensitive streams — tool arguments, memory contents, and incident detail — are sent **metadata-only by default**: free text is replaced with a hash and a size, never the raw content. You see the shape and volume of activity without exfiltrating user content. An operator can opt an individual stream into full payloads when the workspace needs it. ## Where to see it Agent activity and emission coverage surface on the **Observe** area; governance evidence (force-bypass and skipped-gate records) surfaces on the **governance** views. If you ask Sidekick about what LumenFlow captures or about a workspace's governance posture, it will point you to the page that owns the live data. --- ## Approval Flows Category: Governance & Policy URL: https://lumenflow.cloud/docs/bridges-approval-flows ## Approval spectrum LumenFlow supports a spectrum of approval behaviors — from full autonomy (auto-approve) to full control (block). You choose where each action type falls on this spectrum. ## Approval types ### Auto-approve Low-risk actions execute immediately: - Reading calendar events - Searching documents - Generating summaries (no external send) ### Rule-based Actions matching specific criteria are handled automatically: - Emails under 500 words — auto-approve - Calendar events within business hours — auto-approve - Slack messages to bot channels — auto-approve ### Manual approval The user reviews and approves each action individually. This is the default for all actions without a rule. ### Escalation Actions are routed to a specific person or team: - High-cost actions — finance team approval - External communications — manager approval - Data exports — security team approval ### Block Certain actions are never allowed: - Deleting production data - Sending to specific email domains - Exceeding cost thresholds ## Creating an approval flow 1. Go to **Settings → Governance** 2. Click **New Rule** 3. Define the trigger (action type, connection, conditions) 4. Select the approval behavior 5. Set priority (higher priority rules are evaluated first) > **success** > Start with manual approval for everything. As you observe > patterns, add auto-approve rules for low-risk, repetitive actions. --- ## Cost Controls Category: Governance & Policy URL: https://lumenflow.cloud/docs/bridges-cost-controls ## Why cost controls matter AI actions consume tokens, and token costs can add up quickly — especially with multi-step workflows and large context windows. Spending limits prevent surprise bills. ## Spending limits At **Settings → Rules**, create a named limit with: | Setting | Description | |---------|------------| | **Period** | Daily, weekly, or monthly | | **Limit (USD)** | The cap for that period | | **When exceeded** | **Warn** (allow conversations to continue) or **Block** (pause until the period resets) | There is no separate per-action cost cap — a limit applies to all of Sidekick's spend in its workspace for the chosen period. ## How limits are enforced Each limit shows a live gauge of current spend against its cap, with a marker at 75%. Once a blocking limit is reached, new Sidekick actions are paused until the period resets or the limit is raised; a warning limit keeps allowing them and just flags that the cap was hit. ## Monitoring spend Track costs on the workspace overview page — `?panel=costs` for spend by source and project, `?panel=usage` for quota and tier consumption. > **warning** > Spend for a period only settles once usage is metered — treat the > live gauge as close to real time, not instantaneous. --- ## Audit & Compliance Category: Governance & Policy URL: https://lumenflow.cloud/docs/bridges-audit-compliance ## Audit trail Every action in LumenFlow is recorded in an immutable audit trail. Nothing happens in the dark. ## What's logged | Field | Description | |-------|------------| | **Timestamp** | When the action occurred (UTC) | | **Action type** | What Sidekick did (send email, create event, etc.) | | **Initiator** | Who requested the action | | **Approver** | Who approved it (or "auto" for rule-based) | | **Governance rule** | Which rule triggered the approval decision | | **Input data** | The data sent to the action | | **Output data** | The result returned | | **Token usage** | Tokens consumed (prompt + completion) | | **Cost** | Estimated dollar cost | | **Model** | Which LLM model was used | ## Accessing the audit trail ### From Sidekick Ask Sidekick "show me the proof" or "what just happened?" — the Proof widget renders the audit trail inline with replay deep-links. ### From the dashboard Open Jobs, pick a Job, and view its Activity tab for a searchable, filterable view of audit entries scoped to that Job. The org-scoped Observe surface aggregates evidence across the workspace. ### API The audit trail is also accessible via the LumenFlow API for programmatic access and integration with your existing tools. ### Export Export the current evidence set and audit history from the workspace trust surfaces when you need to hand records to reviewers or compliance stakeholders. ## Retention | Plan | Retention | |------|----------| | Free | 7 days | | Team | 90 days | | Enterprise | 365 days | ## Compliance frameworks The audit trail is evidence substrate, not a certification. It produces the kind of records that help teams answer questions from common frameworks — but LumenFlow is not SOC 2 certified or otherwise attested. LumenFlow does not currently offer a Business Associate Agreement. Do not submit protected health information (PHI) to LumenFlow. - **SOC 2** — access logging and change-management records (building toward readiness, not certified) - **GDPR** — data-processing records and right-to-explanation trail - **HIPAA** — action logging and access-control records (no BAA is offered; do not submit PHI) > **info** > Audit entries cannot be modified or deleted. This is by > design — the trail is the ground truth for all AI activity. --- ## Regulated trust posture Category: Governance & Policy URL: https://lumenflow.cloud/docs/regulated-trust-posture ## Regulated-industry governance The regulated-industry tier is agent governance for teams that need cryptographic evidence, policy-gated execution, operator sign-off, residency controls and reproducible audit bundles. ## Live controls | Area | Current posture | |------|-----------------| | **Cryptographic evidence** | Evidence receipts are anchored with a Merkle-style chain so historical tampering can be detected | | **Compliance gates** | GDPR, HIPAA, and finserv packs can fail closed through the gate-resolver path with auditable decline events | | **Operator sign-off** | Mid-execution pause/resume/reject flows compose with dispatch leases and checkpoint events | | **Enterprise auth** | SAML sign-in, SCIM provisioning, and MFA (step-up authentication) policy are live and API-configurable — see [Enterprise Trust](/docs/enterprise-trust) | ## Boundaries | Area | Boundary | |------|----------| | **Data residency** | Key-region, storage-region and evidence-bound routing are enforced; owners pin the workspace region from Dashboard → Trust | | **Audit bundles** | Generated bundles are evidence packages, not attestations | ## What LumenFlow does not claim LumenFlow is not SOC 2 certified, HIPAA certified or otherwise attested. There is no certified integration with a named identity provider, and there is no formal audit attestation. SAML sign-in, SCIM provisioning and MFA policy are live controls. --- ## Roles & Permissions Category: Governance & Policy URL: https://lumenflow.cloud/docs/bridges-role-permissions ## Role hierarchy LumenFlow uses a role-based access control (RBAC) model: | Role | Governance | Connections | Conversations | Billing | |------|-----------|-------------|---------------|---------| | **Owner** | Full | Full | Full | Full | | **Admin** | Create/edit rules | Add/remove | View all | View | | **Member** | View rules | Use existing | Own only | — | | **Viewer** | View rules | — | View assigned | — | ## Permission details ### Governance permissions | Action | Owner | Admin | Member | Viewer | |--------|-------|-------|--------|--------| | Create rules | Yes | Yes | — | — | | Edit rules | Yes | Yes | — | — | | Delete rules | Yes | — | — | — | | View rules | Yes | Yes | Yes | Yes | ### Connection permissions | Action | Owner | Admin | Member | Viewer | |--------|-------|-------|--------|--------| | Add connection | Yes | Yes | — | — | | Remove connection | Yes | Yes | — | — | | Use in Sidekick | Yes | Yes | Yes | — | | View connections | Yes | Yes | Yes | Yes | ## Enterprise governance overlays Enterprise trust adds org-scoped reviewer and admin posture on top of workspace roles. Those reviewers act on the same approval and evidence flow as the workspace, rather than through a separate enterprise-only runtime. ## Best practices - Use the **principle of least privilege** — give users the minimum access they need - Review role assignments quarterly - Separate day-to-day workspace roles from enterprise reviewer posture so sensitive approvals stay with the right audience > **warning** > Only Owners can modify billing settings and delete the workspace. > Ensure at least two people have the Owner role. --- ## Policy Controls Category: Governance & Policy URL: https://lumenflow.cloud/docs/bridges-custom-policies ## What policy means today Policy in LumenFlow is a fixed set of controls that you turn on and tune. There is no policy language you write yourself. You cannot write a rule such as "auto-approve this kind of email when it is cheap and inside working hours", and nothing evaluates conditions you write, such as time of day, day of week, recipient or token count. There are no schedules, exceptions or rule priorities. If you need that, it is not available today. What is enforced today is below. The approval, admission and refusal controls apply at the moment Sidekick calls a tool, before the call runs. The one exception is the check on MCP results, which applies when a result comes back. ## Trust level and approval-required tools A workspace has one autonomy policy, changed in **Settings → Rules** by a workspace owner or admin. It has two parts: **fail-closed** mode, and a list of tools that need approval before they run. The trust levels are presets over those two parts. | Level | Fail-closed | Tools that need approval | |-------|-------------|--------------------------| | **Supervised** | On | Every built-in Sidekick tool, reads as well as writes | | **Balanced** | On | A fixed set of high-impact tools, including sending email, cancelling tasks and initiatives, deleting channels and routines, forgetting memory, changing the workspace model, disconnecting an integration, issuing service tokens, inviting members and changing the policy itself | | **Autonomous** | Off | None | | **Custom** | Either | Any other combination, such as a list you edit tool by tool | With fail-closed on, risky actions on connected apps, such as sending, forwarding or deleting email and cancelling calendar events, also need approval, whichever tools are on your list. A workspace with no saved policy starts fail-closed, and Sidekick falls back to fail-closed if the policy cannot be read. A change is picked up on the next request. ## Approvals When a call needs approval, Sidekick stops and an entry appears in the [Approvals inbox](/docs/approvals-governance). The call does not run until a workspace owner or admin approves it. A rejected request means the call is refused, and a request that is still pending keeps the call held. ## MCP server admission An MCP server you register cannot be used until it is admitted. 1. A workspace owner or admin registers the server. 2. LumenFlow reads the tools the server offers and holds them as a candidate. Nothing on the server can be called yet. 3. An owner or admin admits the candidate. For each tool they set a risk class (read, write or destructive), an approval policy (none, per invocation or always operator), a data classification and limits on results: allowed content types and size. They also record a retention period. It is stored with the decision but is not applied to the results of these servers. The decision is recorded with who made it and why. 4. Only admitted tools can be called. A tool the server offers that was not admitted is refused. Admission is done through the admission API (`POST /api/v1/sidekick/mcp-servers/{id}/admission`). The dashboard has no admission controls, and the **Enabled** switch in **Settings → Connections** cannot admit a server. A tool admitted with an approval policy other than none needs approval on every call, whatever the trust level. A tool admitted with none is not held by admission itself, though the trust level and the checks below still apply to it. After a call returns, its result is checked against the admitted content types, size limits and output schema. A result that does not conform is refused and is not passed to Sidekick, but the call has already run on the server. If a server's tools change after admission, LumenFlow quarantines and disables the server the next time it reads them, and it stays off until an owner or admin readmits it. Owners and admins can also quarantine or revoke a server. See [MCP servers](/docs/sidekick-mcp-servers) for registration. ## Checks that do not depend on trust level These apply on every trust level, including Autonomous: - **Known tools only.** A tool name Sidekick does not recognise is refused outright. It is not sent for approval. - **MCP approval policy.** A tool admitted with an approval policy other than none needs approval on every call. - **Untrusted content.** While Sidekick retains an untrusted-content marker from a connected app or an MCP server, it requires approval before calling a built-in tool classified as write or high-impact, any MCP tool not recorded read-only in its admitted manifest, or any connected-app tool not declared read-only. An MCP tool counts as read-only only when the vendor's annotations pinned at admission say so (read-only true, destructive not true) and the operator did not classify it as write or destructive; a change to those annotations quarantines the server until it is re-admitted. A connected-app action nobody has classified counts as consequential. ## How checks combine A call has to clear every check that applies to it. A refusal, or an approval that is still pending, at any check stops the call, and nothing set elsewhere can override it. A permissive trust level does not undo an MCP tool's approval policy, and an approval does not let through a call that another check has already refused. There is no rule priority, because there are no user-written rules to rank. ## Organization fleet configuration An organization admin can stage and publish a fleet configuration from the Bridge or the API. It has two parts: **requirements**, a floor that lower levels cannot loosen, and **defaults**, a baseline that lower levels may change. It can set five things: sandbox mode, approval policy, an allowlist of MCP servers, permitted network domains and permitted commands. The floor only tightens. Layers resolve in order: cloud, then device management, then the local system. A lower layer can add restrictions or remove entries from an allowlist, but it cannot relax a locked value or add back an entry that a higher layer left out. A configuration that fails validation is rejected when it is staged. Runtimes fetch the active configuration with a workspace API key; LumenFlow does not push it. Publishing records a receipt for each workspace, and a workspace can acknowledge it, so you can see which workspaces are current and which are stale. > **info** > Publishing a fleet configuration does not change what hosted Sidekick > asks approval for or which MCP servers it can use. Hosted approvals > follow the workspace autonomy policy above, and hosted MCP use follows > MCP server admission. ## Previewing a trust level On the **Trust** page of the dashboard, an operator can pick a trust level and a time window to replay recent tool calls against it and see how many it would allow, pause or block. Replay is read-only and changes nothing. The live policy changes only in **Settings → Rules**. ## Not available yet - **Rules you write yourself**, with conditions, schedules, exceptions or priorities, as described at the top of this page. - **Blocking a tool.** **Settings → Rules** shows a Block control for each tool, but a block is not saved or enforced yet. Work on this is in progress. Until it lands, do not use Block to hold a tool back: it can also clear that tool's approval requirement. - **Approval and block toggles for some connected-app actions.** For some connected-app actions, the name that **Settings → Rules** saves does not match the action the connector runs, so a toggle on that row can have no effect. Work on this is in progress. Until it lands, do not rely on a Rules toggle to hold a connected-app action back. ## Related - [Autonomy policies and tool-call approvals](/docs/autonomy-policies) - [Approvals governance](/docs/approvals-governance) - [MCP servers](/docs/sidekick-mcp-servers) - [Cost controls](/docs/bridges-cost-controls), for spending limits - [Fleet management](/docs/fleet-management) --- ## Security Overview Category: Security URL: https://lumenflow.cloud/docs/security-overview ## Security principles LumenFlow is built on three security principles: 1. **Encrypt everything** — data at rest and in transit 2. **Minimize access** — least privilege by default 3. **Log everything** — immutable audit trail for all actions ## How we protect your data LumenFlow uses multiple layers of protection: - **Encryption in transit** — all communications secured with TLS 1.3 - **Encryption at rest** — all stored data is encrypted - **Workspace isolation** — your data is completely separated from other customers - **Input validation** — all inputs are validated and sanitized - **Role-based access** — permissions enforced at every level ## Data handling | Data type | Protection | Retention | Who can access | |-----------|-----------|-----------|----------------| | **API keys** | Encrypted with additional application-level protection | Until revoked | System only | | **Conversations** | Encrypted at rest | Configurable (30–365 days) | Workspace members | | **Audit trail** | Encrypted at rest | Per plan | Workspace members | | **OAuth tokens** | Encrypted with additional application-level protection | Until revoked | System only | ## Third-party access LumenFlow sends your data only to: - **LumenFlow managed inference** — when you use the hosted default - **Your chosen LLM provider** — when you connect a bring your own model key - **Connected services** — via your OAuth tokens - **No other parties** — ever > **success** > LumenFlow does not train models on your data. > Your conversations are not shared with AI providers > beyond the API calls you initiate. ## Reporting a security issue If you find a security issue, email **security@lumenflow.cloud** directly. Include what's affected: - the affected surface (page, API route, or workflow) - steps to reproduce it - the impact you observed - whether any data was accessed Security is a process, not a checkbox here — we treat every report seriously and follow up directly with you. Please limit any testing to your own workspace; do not access, modify, or attempt to reproduce an issue against another customer's workspace or data. There is no paid bug bounty program at this time. --- ## Encryption Category: Security URL: https://lumenflow.cloud/docs/security-encryption ## Encryption in transit All communication is secured with **TLS 1.3**: - Your browser to LumenFlow - LumenFlow to your LLM provider - LumenFlow to your connected services - Webhook deliveries ## Encryption at rest ### Database encryption All data stored in the database is encrypted at the storage level using industry-standard encryption. ### Sensitive field encryption Your API keys and OAuth tokens receive an additional layer of application-level encryption. Encryption keys are unique to each workspace and stored separately from your data, so even in the unlikely event of a data breach, your keys remain protected. ## Key rotation LumenFlow supports encryption key rotation. When rotated, all sensitive fields are re-encrypted with the new key automatically. > **success** > Your API keys are protected by multiple layers of encryption. > They are never logged, never cached, and never sent anywhere > other than your chosen provider. --- ## Access Control Category: Security URL: https://lumenflow.cloud/docs/security-access-control ## Workspace isolation Every piece of data in LumenFlow is scoped to a workspace. Access controls are enforced at multiple layers to ensure no data crosses workspace boundaries — even in the event of an application bug. ## Authentication When you sign in, LumenFlow creates a secure session tied to your identity and workspace. This session determines what data you can access and what actions you can take. ## Role enforcement Roles are checked before any data operation: 1. You authenticate and receive a secure session 2. Your session includes your workspace and role 3. Every request validates your permissions before processing 4. Database-level enforcement provides a second layer of protection ## Token model LumenFlow issues several credential kinds. Each has its own prefix, scopes and revoke path. [Credentials and scopes](/docs/credentials-and-scopes) lists all of them. A request outside a credential's scopes is refused with HTTP 403 and `reasonCode: "insufficient_scope"`, naming the required and granted scopes, and the refusal is written to the audit log. A revoked or unknown credential is refused with 401. A `read` scope covers read requests (GET, HEAD, OPTIONS) and a `write` scope covers every other request; neither implies the other. Workspace API keys carry `read` and `write`, or the scopes you chose when you created or regenerated the key. Keys that existed before scopes keep read and write access. Choose a narrower scope when you create or regenerate a key, for example read only for a dashboard integration. A workspace API key with the write scope is the strongest credential — treat it like a service-account key. > **info** > Access control is enforced at the database level. > Even if application code has a bug, the database prevents > cross-workspace data access. --- ## Credentials and scopes Category: Security URL: https://lumenflow.cloud/docs/credentials-and-scopes ## One reference for every credential LumenFlow Cloud issues several kinds of credential. Each has a fixed prefix, a closed set of scopes, a way to be issued and a way to be revoked. This page is the reference. The developer guide and the security page link here, so they describe the same model. A credential is refused with `401` when it is unknown or revoked. A request the credential is not scoped for is refused with `403`, and the refusal names the scope it needed (see Scope rules below). ## Credential kinds | Kind | Prefix | Scopes it can carry | Issued by | Revoked by | | --- | --- | --- | --- | --- | | Workspace API key | `lf_` | `read`, `write`, and the opt-ins `model_config:write`, `limits:write`, `runners:manage` | `POST /api/v1/workspaces/{workspaceId}/api-key`, which issues or regenerates the key, for a signed-in owner or admin | `DELETE /api/v1/workspaces/{workspaceId}/api-key` | | Org service token | `lf_org_` | `read` by default, and the opt-ins `workspaces:manage` and `members:manage` | `POST /api/v1/orgs/{orgId}/service-tokens`, by an org owner or admin | `DELETE /api/v1/orgs/{orgId}/service-tokens/{tokenId}` | | Inference key | `lf_inf_` | `inference:invoke` only | `POST /api/v1/workspaces/{workspaceId}/inference-keys` | `DELETE /api/v1/workspaces/{workspaceId}/inference-keys/{keyId}` | | App key | `lf_app_` | `payments:checkout.create`, `entitlements:read`, `app_connectors:invoke`, `tool_connections:read`, `tool_connections:connect` | `POST /api/v1/workspaces/{workspaceId}/app-keys`, with the narrowest set of scopes you need | `DELETE /api/v1/workspaces/{workspaceId}/app-keys/{keyId}` | | Runner onboarding grant | `lf_rog_` | The seven `runner:onboard.*` scopes listed below | `POST /api/v1/workspaces/{workspaceId}/runner-onboarding/grants`, with a lifetime of 7 to 30 days (7 by default) | `DELETE /api/v1/workspaces/{workspaceId}/runner-onboarding/grants/{grantId}` | | Engagement token | not a `lf_` key | Read-only, one engagement, filtered by its visibility policy | Per-engagement provisioning in the dashboard | From that engagement's settings | | Dashboard session | not a key | UI actions for the signed-in user | Sign-in to the dashboard | Ends when the sign-in session ends | The revoke paths take effect as follows. - **Workspace API key.** Other instances of the service may keep accepting the old key for up to 15 seconds. The instance that revoked it stops accepting it at once. - **App key and runner onboarding grant.** Refused on their very next use. Neither is served from a cache. - **Org service token.** Refused on the instance that revoked it at once. Other instances honour it for up to 15 seconds. A workspace key may revoke only the inference keys, app keys and runner onboarding grants it issued in its own workspace. An app key, an inference key and a runner onboarding grant revoke nothing. ## Scope rules - **Read and write.** `read` covers the safe methods, `GET`, `HEAD` and `OPTIONS`. `write` covers every other method. Neither implies the other. - **Opt-in scopes.** `model_config:write`, `limits:write`, `runners:manage`, `workspaces:manage` and `members:manage` are never given by default. You name them when you issue or rotate the credential. None of them implies `read` or `write`. - **Fixed sets.** An inference key carries exactly `inference:invoke`. An app key never carries `read` or `write`. A runner onboarding grant carries only `runner:onboard.*` scopes and is accepted only by the runner onboarding endpoints. Any other route answers a grant with `403 runner_onboarding_grant_not_accepted`. - **Org tokens never write.** An org service token cannot hold `write`. It can rotate a workspace's primary key with an explicit scope selection, but it cannot hold those scopes itself. - **Unknown scopes fail closed.** A scope the credential was not issued with grants nothing. Anything not in the list below is refused. - **Existing keys.** A workspace key created before scopes existed keeps `read` and `write`. Choose narrower scopes when you create or regenerate a key, for example `read` only for a dashboard integration. A refused request returns `403` with this body: ```json { "error": "This credential does not carry the \"write\" scope required for this request.", "reasonCode": "insufficient_scope", "requiredScope": "write", "grantedScopes": ["read"] } ``` Each refusal is written to the audit log. ## Scope reference | Scope | Carried by | What it allows | | --- | --- | --- | | `read` | Workspace API key, org service token | Read requests for the key's workspace, or for the token's organisation. | | `write` | Workspace API key | Every request that changes state, for the credential's workspace. | | `model_config:write` | Workspace API key (opt-in) | Manage the workspace's own model routes. | | `limits:write` | Workspace API key (opt-in) | Set the workspace's and its inference keys' self-service limits, within the plan and platform ceilings. | | `runners:manage` | Workspace API key (opt-in) | Issue and revoke runner onboarding grants for the workspace. | | `workspaces:manage` | Org service token (opt-in) | Create, list and archive workspaces of its own organisation, and rotate their primary keys. | | `members:manage` | Org service token (opt-in) | Invite, list, change the role of and remove members of its own organisation's workspaces. It never assigns or removes the owner role. | | `inference:invoke` | Inference key | Make governed inference calls. See [Governed inference API](/docs/governed-inference). | | `payments:checkout.create` | App key | Create a checkout for the app. | | `entitlements:read` | App key | Read the entitlements of the app. | | `app_connectors:invoke` | App key | Invoke an app connector. | | `tool_connections:read` | App key | Read the outcome of a tool connection attempt and the app's own connections. | | `tool_connections:connect` | App key | Start a tool connection attempt for the app. | | `runner:onboard.policy.read` | Runner onboarding grant | Read the onboarding policy. | | `runner:onboard.code.mint` | Runner onboarding grant | Mint a pairing code for a runner. | | `runner:onboard.runner.read` | Runner onboarding grant | Read the runners onboarded under the grant. | | `runner:onboard.capabilities.approve` | Runner onboarding grant | Approve the capabilities a runner requests. | | `runner:onboard.request.read` | Runner onboarding grant | Read onboarding requests. | | `runner:onboard.runner.revoke` | Runner onboarding grant | Revoke an onboarded runner. | | `runner:onboard.receipt.read` | Runner onboarding grant | Read onboarding receipts. | ## Who am I `GET /api/v1/auth/whoami` returns the kind, id, prefix, org, workspace, scopes and name of the credential you present. Any credential may call it, and it never returns a secret or a hash. For a dashboard session it returns the user id and the organisations the user belongs to. `expires_at` is `null` for every credential kind. ## Related - [Governed inference API](/docs/governed-inference) for inference keys and the limits that apply to them. - [Jobs lifecycle](/docs/jobs-lifecycle) for the job routes a workspace key may call. - [Which credential is for what](/docs/connected-compute-credentials) for runner and pairing credentials. --- ## Compliance & Privacy Category: Security URL: https://lumenflow.cloud/docs/security-compliance ## Data privacy ### What we collect | Data | Purpose | Retention | |------|---------|-----------| | **Email address** | Authentication | Account lifetime | | **Conversations** | Sidekick functionality | Configurable | | **Audit trail** | Compliance, debugging | Per plan | | **Usage metrics** | Billing, analytics | 2 years | ### What we don't collect - Conversation content for model training - Browsing behavior outside the dashboard - Data from connected services beyond what you request ## GDPR compliance LumenFlow supports GDPR requirements: | Right | How to exercise | |-------|----------------| | **Access** | Export all data from Settings → Privacy | | **Rectification** | Edit profile in Settings → Account | | **Erasure** | Delete account from Settings → Account | | **Portability** | Export data as JSON/CSV | | **Objection** | Contact privacy@lumenflow.cloud | ## Data residency | Component | Location | |-----------|---------| | **Application and data** | EU (Frankfurt) | | **LLM calls** | LumenFlow managed inference or your chosen provider's infrastructure; a workspace pin refuses any call whose key region would cross the pinned region | | **Workspace pin** | Owners with the residency entitlement pin the workspace region from **Dashboard → Trust → Data residency**; the pin is audited and enforced on every production model call and residency-relevant storage write | Pinning is a purchasable entitlement (included on Enterprise, or when your organisation has been granted the residency option). An unentitled workspace sees a refusal explanation and cannot save a pin. Entitled workspaces pin to eu_west, us_east, us_west, or apac. A cross-region model call or storage write for a pinned workspace is refused and leaves a residency-violation receipt. ## Public trust surfaces - **[Trust Centre](/docs/trust-centre)** — customer-facing guide to the public trust centre, sub-processors register, live status feed, and the in-product Trust dashboard - Public pages: [/trust](/trust) (readiness), [/subprocessors](/subprocessors) (versioned register), [/status](/status) (live health) ## SOC 2 readiness LumenFlow is building toward SOC 2 Type II readiness: - **Controls in product** — action history, evidence capture, access posture - **Operational baseline** — encryption, monitoring, and recovery practices - **Audit preparation** — export and review surfaces that support formal assurance work This is readiness work, not a certification claim. ## Responsible AI - All AI actions go through governance (no uncontrolled execution) - Audit trail provides explainability for AI decisions - Users control autonomy levels per action type > **info** > LumenFlow does not currently offer a Business Associate Agreement. Do not > submit protected health information (PHI) to LumenFlow. --- ## Billing Overview Category: Billing URL: https://lumenflow.cloud/docs/billing-overview ## Billing model LumenFlow uses a hybrid billing model: 1. **Plan fee** — the monthly price of your plan, see [Plans & Pricing](/docs/billing-plans-pricing) 2. **Managed inference usage** — paid from your workspace's inference wallet and metered per call (see Your inference wallet) 3. **BYOK provider usage** — billed by your chosen model provider when applicable 4. **Governed execution (BYOC)** — an included monthly allowance of execution time, metered overage beyond it on paid plans, for Connected Compute work you run on your own hardware. This allowance is for compute time, not AI usage. Work run on LumenFlow-managed compute is billed separately under the managed-compute credit model, not this item. You pay LumenFlow for the platform, any managed inference you use, and governed execution time on your own hardware. If you connect a bring your own model key, that provider bills the model usage directly. ## How metering works Every interaction with Sidekick consumes tokens: | Component | Tokens | |-----------|--------| | **System prompt** | ~500 (fixed overhead) | | **Your message** | Varies by length | | **Conversation history** | Grows with conversation | | **Tool definitions** | ~200 per connected tool | | **Response** | Varies by complexity | Token usage is tracked per action and displayed in **Observe → Analytics**. ## Payment methods - **Credit card** — Visa, Mastercard, Amex - **Invoice** — Available for Enterprise arrangements ## Billing cycle - Plan fees are charged on the 1st of each month - Token usage is metered in real-time - Invoices are available in **Settings → Billing → Invoices** > **info** > Free plan users don't need a payment method. > You'll be prompted to add one when upgrading or topping up prepaid > inference credit. Managed inference has no included allowance: it is paid > from your prepaid inference credit. ## Ask Sidekick directly You don't have to open this page to check where things stand. Ask Sidekick things like "what's our current plan" or "what's our inference credit balance" in chat, and it answers with your workspace's real numbers — plan tier, subscription status, and your prepaid inference credit balance. --- ## Plans & Pricing Category: Billing URL: https://lumenflow.cloud/docs/billing-plans-pricing ## Plan comparison | Feature | Free | Team | Enterprise | |---------|------|------|------------| | **Price** | $0/mo | $49/mo | Custom | | **Workspaces** | 1 | Up to 5 | Unlimited | | **Events per day** | 1,000 | 50,000 | Unlimited | | **Data retention** | 7 days | 90 days | 365 days | | **Managed inference** | From the inference wallet | From the inference wallet, metered per call | Volume pricing | | **Bring your own model key** | — | Yes | Yes | | **Action history** | Yes | Yes | Yes | | **Audit export** | — | — | Yes | | **Enterprise governance** | — | — | Yes | | **SSO / SAML** | — | — | Live | | **Support** | Community | Priority | Dedicated channel | ## Upgrading 1. Go to **Settings → Billing** 2. Click **Upgrade Plan** 3. Select your new plan 4. Enter payment information 5. Changes take effect immediately ## Downgrading Downgrading takes effect at the end of your billing cycle. Features from the higher plan remain active until then. > **warning** > Downgrading may disable features you're currently using. > Review the comparison table before downgrading. --- ## Usage Tracking Category: Billing URL: https://lumenflow.cloud/docs/billing-usage-tracking ## Usage dashboard Navigate to **Settings → Billing → Usage** to see: ### Current period - **Tokens used** — total tokens consumed this billing cycle - **Credit balance** — how much prepaid inference credit remains - **Estimated cost** — projected LLM provider cost based on usage ### Breakdown | Dimension | Description | |-----------|------------| | **By model** | Which LLM models consumed the most tokens | | **By action type** | Email, calendar, search, etc. | | **By team member** | Individual usage (Team plan) | | **By day** | Daily consumption trend | ## Usage API Usage data is also accessible via the LumenFlow API for integration with your existing reporting tools. The API returns your current billing period, token usage, credit balance, and estimated costs. > **success** > Review usage weekly during your first month to understand > consumption patterns and set appropriate budgets. --- ## Spending Limits Category: Billing URL: https://lumenflow.cloud/docs/billing-budgets-alerts ## Spending limits live in Rules There is no separate Budgets screen. Spending caps are configured at **Settings → Rules**, alongside the rest of Sidekick's autonomy policy — what it can do without asking, and where the spend rails sit. ## Creating a limit 1. Go to **Settings → Rules** 2. Click **+ Add limit** 3. Name it, choose a **Period** (daily, weekly, or monthly), and set the **Limit (USD)** 4. Choose what happens **when exceeded**: **Warn** (allow conversations to continue) or **Block** (pause conversations until the period resets) ## Watching spend Each limit shows a live gauge — current spend against the limit, with a marker at 75% and a badge that turns to warning color there and to destructive color once the limit is reached. A blocking limit at 100% shows "Blocked — limit reached"; a warning limit shows "Warning — limit reached" and keeps allowing conversations. ## Managing limits Limits can be deleted at any time from the same Rules card. There is no separate per-member budget — every limit is workspace-scoped and applies to all of Sidekick's spend in that period. --- ## Common Issues Category: Troubleshooting URL: https://lumenflow.cloud/docs/troubleshooting-common-issues ## "Model configuration required" **Cause:** Managed inference is unavailable for the workspace and no bring your own model key is configured. **Fix:** 1. Ask a workspace admin to enable managed access if your plan allows it 2. Or go to **Settings → Model Configuration** 3. Select a provider (OpenAI, Anthropic, or Google) 4. Paste your API key and save the workspace config ## "Connection expired" **Cause:** The OAuth token for a connected service has expired. **Fix:** 1. Go to **Settings → Connections** 2. Find the service showing "Expired" 3. Click **Reconnect** 4. Re-authorize in the OAuth flow ## "Action blocked by governance" **Cause:** A governance rule is preventing the action. **Fix:** 1. Check **Settings → Governance** for matching rules 2. Either modify the rule or approve the specific action manually 3. If you're not an Admin/Owner, ask your workspace admin ## "Budget exceeded" **Cause:** A spending limit configured in Rules has been reached. **Fix:** 1. Go to **Settings → Rules** 2. Raise the limit, change it to warn instead of block, or wait for its period (daily/weekly/monthly) to reset 3. Consider switching to a model with lower per-token costs ## "Rate limited" **Cause:** Too many API requests in a short period. **Fix:** 1. Wait for the duration in the `Retry-After` header 2. Reduce request frequency in your integration 3. Consider upgrading your plan for higher limits ## Sidekick not responding **Cause:** Multiple possible causes. **Checklist:** 1. Check your LLM provider's status page 2. Verify your API key is valid in **Settings → API keys** and the workspace model source is configured in **Settings → Models** 3. Check token budget hasn't been exceeded 4. Try a new conversation (the current context may be too large) > **info** > Ask Sidekick "what just went wrong?" — the Proof widget surfaces the recent > audit trail. For per-job detail, open Jobs → Job, then the > Proof section, and look for error events around the time the issue occurred. --- ## Error Code Reference Category: Troubleshooting URL: https://lumenflow.cloud/docs/troubleshooting-error-codes ## Error code format LumenFlow errors follow the format `EXXXX` with a human-readable message and additional context for debugging. ## Authentication errors (E001-E009) | Code | Message | Resolution | |------|---------|-----------| | `E001` | Invalid API key | Check your workspace token in Settings | | `E002` | Token expired | Generate a new token | | `E003` | Insufficient scope | Request the needed scope when creating the token | | `E004` | Session expired | Sign in again | ## Provider errors (E010-E019) | Code | Message | Resolution | |------|---------|-----------| | `E010` | Provider unavailable | Check your LLM provider's status page | | `E011` | Invalid provider key | Verify your API key with the provider | | `E012` | Provider rate limited | Wait and retry; consider a different model | | `E013` | Model not available | Choose a different model in settings | ## Governance errors (E020-E029) | Code | Message | Resolution | |------|---------|-----------| | `E020` | Action blocked by rule | Review governance rules in settings | | `E021` | Approval required | Approve the pending proposal | | `E022` | Escalation needed | Route to the designated approver | | `E023` | Policy conflict | Two rules conflict — adjust priorities | ## Budget errors (E030-E039) | Code | Message | Resolution | |------|---------|-----------| | `E030` | Budget exceeded | Increase budget or wait for reset | | `E031` | Per-action limit exceeded | Simplify the request or raise the limit | | `E032` | Daily action limit reached | Wait until tomorrow or raise the limit | ## Connection errors (E040-E049) | Code | Message | Resolution | |------|---------|-----------| | `E040` | Connection not found | Add the connection in settings | | `E041` | Connection expired | Reconnect via OAuth | | `E042` | Insufficient permissions | Re-authorize with required scopes | | `E043` | Service unreachable | Check the external service's status | > **success** > Include the error code and `details` field when contacting > support. This helps us diagnose issues quickly. --- ## Getting Support Category: Troubleshooting URL: https://lumenflow.cloud/docs/troubleshooting-support ## Support channels | Channel | Availability | Best for | |---------|-------------|----------| | **Documentation** | Always | Self-service answers | | **Community forum** | Always | Discussion, tips, feature requests | | **Email support** | Team + Enterprise | Account issues, bugs | Enterprise customers may also have a dedicated support channel named in their contract. No published response-time commitment exists until one is written into that contract — this article does not invent one. ## Before contacting support Gather this information to help us resolve your issue quickly: 1. **Workspace ID** — found in Settings → General 2. **Error code** — the `EXXXX` code from the error message 3. **Timestamp** — when the issue occurred (UTC) 4. **Steps to reproduce** — what you were doing when it happened 5. **Screenshots** — if the issue is visual For trust, sub-processors, residency, and compliance-pack questions, start with the [Trust Centre](/docs/trust-centre) article. For whether the public API or database probe is reachable right now, open [/status](/status) — live rows from the health feed, or **Unknown** when that feed cannot be reached. That surface does not publish uptime history, a past-incident feed, or a response-time commitment. ## Email support Send issues to **support@lumenflow.cloud** with: - Subject: `[workspace-id] Brief description` - Body: error code, timestamp, steps to reproduce - Attachments: screenshots, API response bodies Response times: | Plan | Response time | |------|--------------| | Team | Business-hours queue | | Enterprise | Dedicated channel when contracted | ## Community forum Visit the community forum for: - Feature requests and voting - Tips and best practices - Integration showcases - Bug reports (for non-urgent issues) > **success** > Most common issues are covered in the > [Troubleshooting](/docs/troubleshooting-common-issues) guide. > Check there first before contacting support. --- ## Outputs, artifacts, and destinations Category: Sidekick URL: https://lumenflow.cloud/docs/outputs-artifacts-destinations ## The short version An **output** is something Sidekick or another governed agent produced: a file, draft, bundle, report, patch, replay package, or deployment record. An **artifact** is the governed record behind that output. It tells LumenFlow what was produced, which agent or participant produced it, which job or handoff it belongs to, where it lives, who can access it, and which evidence, replay, or approvals are attached. A **destination** is the place an output should land: managed artifacts inside LumenFlow, a code host, a document store, an artifact store, a deployment provider, a connected runtime, or a manual export path. ## Managed links, hosted app pages, and connected deployments Saving something and making it public are different actions, and LumenFlow keeps them clearly separate. When a governed agent saves a generated file in managed artifacts, LumenFlow can give workspace members and authorized participants a view, download, preview, or export link. That link is workspace-scoped and governed by your workspace permissions. It is not a public website, CDN, custom domain, or production deployment. If you ask Sidekick, an external agent, or a fleet worker to "host this page," there are two honest paths, and LumenFlow always tells you which one applies before anything goes live: 1. **A hosted app page** — a small, self-contained page (a demo, prototype, or utility) can be published directly on LumenFlow's own managed hosting as a sandboxed, revocable public page. Nothing goes live until you explicitly confirm; once published, anyone with the link can view it until it's taken down. See [Hosted app pages](/docs/hosted-app-pages). 2. **A connected deployment destination** — Sidekick can deploy a built site to a destination you've connected and approved, such as GitHub Pages or your own Vercel project, rather than hosting it itself. This is for a site that ships as static files; a full app that needs its own backend, database, or server-side code is beyond what Sidekick deploys for you. Either way, the agent only ever tells you a public link exists once the publish or deployment step has actually returned one — never a guess, and never in advance. ## How Sidekick fits the platform Sidekick is one surface of LumenFlow, a governed agent runtime and control plane. The same policy, approvals, budgets and evidence apply to every surface. Artifacts are the handoff objects. They keep proof and routing straight, while your own tools remain the source of truth for code, documents and deployments. ## What people can build LumenFlow-governed agents can help you build: - software changes with tests and pull requests - generated documents, summaries, reports, and export bundles - small static files or HTML pages as workspace-scoped outputs, or published directly as a hosted app page - replay and evidence packages for audit or review - workflow definitions and connected-app actions - deployable code or assets that are ready to hand to a connected destination A simple, self-contained page can be published directly as a hosted app page once you confirm. They cannot turn an internal output into a full production website with a backend by themselves — that always routes to a connected deployment destination, with your explicit confirmation and a real URL returned by that step. ## Common terms | Term you may see | Plain label | What it means | |------------------|-------------|---------------| | **Artifact** | Output, generated file, export | Something Sidekick or another governed agent produced and saved with a traceable record. | | **Job** | Work, task | A tracked piece of work one or more governed agents are carrying out for you or your team. | | **Runtime** | Worker, execution environment | The place where governed work runs, whether hosted by LumenFlow or connected from your environment. | | **Pack** | Capability, workflow type | A bundle of rules and tools for a kind of work, such as software delivery. | | **Destination** | Connected tool, publish target | The app or service where an output should land. | | **Evidence** | Proof, activity record | The record of what happened, who approved it, and which rules applied. | | **WU** | Task, change | A scoped software-delivery task with files, gates, and evidence. | On desktop, these terms should have helper text or info tooltips. On mobile, they should use tap-to-open explanations, inline help, or bottom sheets rather than hover-only tooltips. ## Can LumenFlow host what I build? Yes, within a defined scope. For a simple page — a demo, prototype, or small utility — LumenFlow can publish it directly on its own managed hosting as a sandboxed, revocable page once you confirm. LumenFlow is not the canonical host for a full production website: for a full app that needs a backend, a database, or server-side code, it routes the code to the deployment destination you've connected and approved instead of hosting it itself. For code and deployment, LumenFlow works with the systems you choose. Your code host remains the source of truth for source code. Your connected deployment destination remains the source of truth for a full production deployment. --- ## How LumenFlow looks: jobs, agents, and proof Category: Sidekick URL: https://lumenflow.cloud/docs/how-lumenflow-looks ## Sidekick is the front door When you open LumenFlow, you land in Sidekick. You ask for what you need, Sidekick plans the work, agents do it, and you approve when a decision is needed. You do not need to learn another surface to get work done. LumenFlow's product direction is to show visual structure inside the conversation: plans, approvals, output previews, proof, and the agents involved. ## The words you will see LumenFlow uses plain words for the things you interact with: | Word | What it means | |------|---------------| | **Ask** | What you say you need | | **Job** | The thing LumenFlow is handling for you | | **Steps** | What will happen, in order | | **Agents** | Who or what is doing the work | | **Connections** | The apps and services LumenFlow can use | | **Rules** | What LumenFlow is allowed to do | | **Approvals** | Where you need to decide | | **Outputs** | The files, docs, code, or results produced | | **Proof** | The record of what happened and why | ## What Sidekick can show you Sidekick is a conversation, but it can render structure inline when structure helps. The visual direction is to make panels like these available in the chat as the widget system grows: - **Plan** — the steps for a job, editable and approve-to-run - **Connections** — what's wired up, what's missing, one tap to connect - **Approvals** — approve or deny without leaving the conversation - **Outputs** — preview, download, or send a generated file or result - **Proof** — the record of what happened and the replay of how - **Agents** — who is working on this right now and how they're handing off - **Publish/Send** — pick the connected destination, confirm, and go These are visual without being a separate canvas. LumenFlow stays one surface. ## What Agents is, and is not Agents is the operator depth surface. Today it shows job progress, safe operator actions, outputs and live runtime activity. Agents is not the place a consumer goes to do work. For making something, asking a question, approving, or reviewing — stay in Sidekick. ## Where things live Three top-level surfaces, each with one job: | Surface | What it is for | |---------|----------------| | **Sidekick** | The conversation. Ask for outcomes, see plans, approve actions, review outputs and proof — all inline as widgets in the chat. | | **Settings** | Configuration. Connections, rules, approvals policy, notifications, API keys, model defaults, and your memory preferences all live here in one consistent shell. | | **Agents** | Operator depth. The job graph, safe operator actions, outputs and live runtime activity — for users running the agents, not asking them for work. | Jobs is the workspace overview for users who want a non-conversational list view of jobs. It is reachable from Sidekick and from the sidebar. Objectives — outcomes you've delegated to Sidekick in conversation — has its own review page too; see [Objectives](/docs/objectives). You will not see a long list of separate `/sidekick//` pages for tasks, today, activity, tools, integrations, or model config. Those have moved: configuration into Settings, governance memory into Agents, and the job-adjacent list views into Sidekick widgets and Jobs. --- ## Managed storage and managed runtime Category: Sidekick URL: https://lumenflow.cloud/docs/managed-storage-defaults ## Two managed defaults Every workspace starts with two system-managed destinations that work out of the box: | Destination | What it stores or runs | When it's used | |-------------|------------------------|----------------| | **Managed artifacts** | Generated docs, files, export bundles | When no `document_store` or `artifact_store` connector is pinned | | **Managed runtime** | Builder execution (the work itself) | When no external runtime is enrolled | Both are encrypted, workspace-isolated, and visible in the workspace evidence and artifact views. ## When to use managed vs connected Managed defaults are the right choice when: - You're trying Sidekick for the first time and don't want to set up GitHub, Notion, or a runtime yet - The output is internal — drafts, summaries, exports, generated files — that doesn't need to live in a team-owned tool - You want everything in one governed place rather than scattered across third-party services Connect external destinations when: - The output belongs in a team-owned source of truth (code in GitHub, docs in Notion, designs in Figma) - Your audit / compliance setup mandates retention in your own systems - You want Sidekick to use a runtime you already operate - You want a generated website or application deployed to public hosting ## Switching destinations In **Settings → Destination defaults**, owners and admins can pin specific destinations per role (code, document store, artifact store, deployment host, runtime). Roles without a pinned destination fall back to the managed default where one exists. ## Governance Managed storage inherits workspace-level encryption, role gates, and audit. There's no extra approval to use it — but Sidekick still records the artifact in the evidence trail so you can replay any action that produced it. Managed artifact links are workspace-scoped. They are for review, download, preview, or export inside your workspace boundary. They are not public hosting links. > **info** > If you're worried about "where did that file go?", the [Evidence Vault](/docs/evidence-vault) shows every artifact Sidekick produced, where it landed, and the action that created it. --- ## Builder destinations and publication workflow Category: Sidekick URL: https://lumenflow.cloud/docs/builder-destinations ## How destinations get chosen Sidekick resolves a destination per role at build time: 1. **Pinned destination** — if you've pinned a connector for that role (e.g. GitHub for `code_host`), Sidekick uses it. 2. **Managed default** — if nothing is pinned, Sidekick falls back to the matching managed default (managed artifacts for files, managed runtime for execution). 3. **Approval** — if the destination is gated by autonomy policy, Sidekick pauses for approval before publishing. ## Roles and what they cover | Role | Typical destination | Managed fallback | |------|---------------------|------------------| | `code_host` | GitHub | Internal code bundle or manual export; pull requests require a connected code host | | `document_store` | Notion, OneDrive | Managed artifacts | | `artifact_store` | OneDrive, GitHub Releases | Managed artifacts | | `deployment_host` | GitHub Pages, Vercel | No connected deployment; a simple page can still publish as a hosted app page, or export manually for a PR-ready handoff | | `runtime_target` | Connected runtime / fleet | Managed runtime | ## Pinning a destination In **Settings → Connections → Destination defaults**, choose a connector for each role you want to override. Unpinned roles continue to use the managed default. ## Publication approval For destinations marked as approval-gated by your autonomy policy, Sidekick: 1. Drafts the change in its isolated worktree 2. Surfaces a publication approval in the [Approvals inbox](/docs/approvals-governance) 3. Publishes only after the approval resolves ## Capability boundary Sidekick won't pin a destination on your behalf. The first time it touches a role with no pin and no connector, it uses the managed default and records that decision in the evidence trail so you can opt in to a different destination later. If there is no deployment host connected, Sidekick may produce a deployable output, export bundle, or pull request, but it should not claim that a public URL exists for a full app. A simple, self-contained page is different: Sidekick can still publish it directly as a hosted app page, with your explicit confirmation. Either way, Sidekick only ever states a public URL once the publish or deployment step has actually returned one. > **info** > See [Outputs, artifacts, and destinations](/docs/outputs-artifacts-destinations) and [Hosted app pages](/docs/hosted-app-pages) for the plain-language boundary between internal outputs, hosted app pages, and public deployment. --- ## Landing preference: Dashboard vs Sidekick Category: Sidekick URL: https://lumenflow.cloud/docs/landing-preference ## What it is When you open a workspace, you land on one of two surfaces: - **Sidekick** — the conversation. Ask, delegate, see what's happening, and act on suggestions inline. - **Dashboard** — the workspace dashboard with the full operator view. New users default to Sidekick. Existing users keep Dashboard unless they choose otherwise. ## Where to change it **Settings → Workspace landing.** Pick Dashboard or Sidekick. The change applies only to your view of this workspace — teammates keep their own preference. ## Disclosure-only Landing preference is a personal display setting. It does **not**: - Change your role - Grant or remove access to any surface - Change what teammates see Demo workspaces always land on Playground regardless of preference; builder workspaces always land on Dashboard. ## Why this exists Sidekick is the front door for most consumers — it's where work gets asked, planned, and tracked in one place. Dashboard remains a first-class alternative for operators who prefer the dashboard view. > **info** > See [Sidekick Overview](/docs/sidekick-overview) for what the conversation surface offers and [Dashboard](/docs/dashboard-overview) for the dashboard. --- ## Governed Sidekick execution Category: Sidekick URL: https://lumenflow.cloud/docs/governed-sidekick-execution ## Long-running work is still governed work Sidekick can now represent more than a single chat turn. The May 2026 runtime delivery added the substrate for cloud-resident work: stored intent, bounded resume, checkpoint events, approval pauses, and evidence at every transition. The important rule is unchanged: Sidekick must not claim progress without an event. Long-running work is visible as a Job with Steps, Approvals, Outputs, and Proof. ## What shipped | Capability | What it means | |------------|---------------| | **cloud-resident execution** | Sidekick can hold a bounded workspace-resident job instead of pretending every ask finishes in one turn | | **parallel subagent fanout** | A parent Job can dispatch a bounded, fixed-size set of parallel Agents under it — each inherits the parent's scope and connections (never wider), each produces its own proof, and the fan-out still rolls up into one parent record. Bounded and deterministic, not an open-ended swarm. | | **multi-step delivery graphs** | A Job isn't always one straight line of Steps — it can branch into several linked pieces of work with dependencies between them, some of which can run at the same time under the bounded fan-out above, then converge into one outcome. | | **behaviour-drift evidence** | Drift is surfaced as evidence and candidate follow-up work; it is not auto-applied self-modification | | **routine studio** | Non-engineers can compose versioned routines through a governed routine studio rather than needing a developer to hand-code every workflow | | **governed browser connector** | Browser-like actions are connector actions inside the federation/runtime boundary, not uncontrolled local computer use | | **async continuation** | When a background job finishes, Sidekick picks up the conversation automatically — its follow-up appears in your thread without a reload or a new message from you. | ## What this is not This is not an opaque autonomous swarm. Scope inheritance, approvals, budget checks, connector admission, evidence receipts, and replay remain load-bearing. If a required connection, gate, or approval is missing, Sidekick should say that plainly and pause or refuse. ## How to talk about it Use consumer words first: Ask, Job, Steps, Agents, Approvals, Outputs, Proof. Use runtime words when precision matters: resident agent record, checkpoint event, dispatch lease, connector event, and evidence receipt. Sidekick follows up in your thread when its background work is done. You do not need to ask — it comes to you. --- ## Autonomy policies and tool-call approvals Category: Governance & Policy URL: https://lumenflow.cloud/docs/autonomy-policies ## What policy controls Every Sidekick action is checked against three gates before it runs: 1. **Tool-call gate** — is this tool allowed at all in this workspace? 2. **Approval-required list** — does this specific tool need a human OK? 3. **Budget gate** — would this action exceed the workspace cost or token cap? If all three pass, Sidekick runs the action. If any fail, Sidekick either pauses for approval or refuses, depending on the policy. ## Trust levels Trust levels are presets that wire the three gates for common operating shapes: | Level | Tool-call gate | Approval-required tools | Best for | |-------|----------------|-------------------------|----------| | **Supervised** | Read-only by default | Almost everything | New workspaces, sensitive data | | **Balanced** | Reads + low-risk built-in writes | Risky built-in tools (cancels, deletes, sends, credential and policy changes) and every built-in connector action that is not a read | Most teams | | **Autonomous** | Most tools allowed | None by default; the untrusted-content rule below still applies | Trusted internal use cases | | **Custom** | You define | You define | When presets don't fit | Choose a level in **Settings → Rules**. You can switch any time; the new policy takes effect on the next action. ## What's always approval-gated One rule holds at every trust level, including Autonomous: after Sidekick reads content from a connected app or MCP server, every consequential action that follows within the same conversation (or routine run) requires human approval. An action that is not tied to a conversation or routine run at all is treated the same way and is refused until it is started from one. - **What counts as consequential** — anything that sends, shares, writes, updates, deletes, cancels, books, or deploys. An action on a built-in connector counts as consequential unless it is known to only read, so a new or unclassified action is held, not allowed. An MCP tool counts as consequential unless the vendor's read-only claim was pinned in its admitted manifest; the content it returns is still treated as untrusted. - **Why** — content from connected apps and MCP servers is treated as untrusted, so an instruction hidden in an email or document cannot trigger one of these actions on its own. - **How long** — the hold lasts 30 minutes from the read. These rules also apply at every trust level: - Any tool on your approval-required list needs approval before it runs. - Calls to MCP tools admitted with an approval policy other than none need approval before they run. - Any tool covered by the classified-tool untrusted-content check described in [Policy Controls](/docs/bridges-custom-policies) needs approval before it runs. - Any tool that is not on the workspace tool-call allowlist is rejected before it runs. Balanced holds every built-in connector action that is not a read, whether or not Sidekick has read anything first. Drafts, labels, archiving and read-state changes are held too, and so is any action nobody has classified yet. Supervised holds them as well. Autonomous does not, unless the rule above applies or you add the tool to your approval-required list. Sidekick can never raise its own autonomy — it can only ever ask for tighter checks, not looser ones. ## Tool-call approval flow When an action needs approval: 1. Sidekick pauses and surfaces an entry in the [Approvals inbox](/docs/approvals-governance) 2. The entry shows the tool, the inputs, and the policy basis 3. An owner or admin approves or rejects 4. Sidekick resumes (or aborts) based on the decision 5. The full approval trail lands in the [Evidence Vault](/docs/evidence-vault) ## Budget-driven approvals Budget gates trip when an action would push the workspace over its cost or token cap (configured in **Settings → Spending limits**). The approver sees the projected spend and can approve, reject, or raise the limit. > **info** > See [Approvals governance](/docs/approvals-governance) for the approver-side workflow and [Approval workflows](/docs/approval-workflows) for cross-team routing. --- ## EU AI Act Article 12 readiness Category: Governance & Policy URL: https://lumenflow.cloud/docs/eu-ai-act-article-12-readiness ## What changes on August 2, 2026 The EU AI Act's record-keeping and oversight obligations for Annex III high-risk AI systems become enforceable on August 2, 2026. Penalties for non-compliance reach €15 million or 3% of worldwide annual turnover, whichever is higher. As of this writing, no finalised technical standard exists yet for Article 12 logging — drafts including prEN 18229-1 and ISO/IEC DIS 24970 are still in development. That gap is a procurement reality: regulated buyers need to demonstrate compliance before the standards are finished. LumenFlow's primitives map directly to the obligations. ## Article 12 — automatic record-keeping | Requirement | LumenFlow primitive | |---|---| | Automatic logging over the lifetime of the system | Evidence receipts emitted at every governed tool call, persisted to the evidence store | | Traceability of inputs to outcomes | Content-addressed input hashes, output hashes, scope snapshots, and policy-version snapshots inside each receipt | | Tamper-resistance | Every evidence receipt is hash-chained; receipts written since per-receipt signing was enabled carry an Ed25519 signature checkable against a published public key | | Lifetime preservation | Append-only receipt store with retention controls and an export envelope for regulator hand-off | ## Article 14 — human oversight | Requirement | LumenFlow primitive | |---|---| | Effective oversight by a natural person during use | Approvals as a first-class noun: risky tool calls pause execution and route to a workspace inbox | | Ability to intervene or interrupt | Deny-wins Rules cascade evaluated before the action runs; an Approval can withhold or revoke without after-the-fact rollback | | Specific dual-confirmation for Annex III point 1(a) | Approval workflows support multi-approver routing; the approval record captures both confirmations and timestamps | ## Article 15 — robustness, accuracy, cybersecurity LumenFlow's contribution to Article 15 obligations is not the model itself — it is the boundary around the model. Per-Connection identity, short-lived enrolment tokens, signed Packs with integrity pins, and import-boundary enforcement reduce the supply-chain and lateral-movement attack surface around the AI system. ## What a buyer actually gets For an Annex III deployer, LumenFlow provides four artefacts that map to the obligations above: 1. **A hash-chained evidence receipt per governed action** — the canonical record of what the system did, under which policy, with what scope, for which Ask. Receipts written since per-receipt signing was enabled also carry an Ed25519 signature checkable against a published public key; a detached-signed bundle with a third-party-runnable verifier CLI exists in the trusted-compute demo, not yet as a per-action production artefact. 2. **An independent verify path** — a public function that recomputes every content hash, chain hash, and (where present) signature from only a public key and the stored receipt rows, with no database access required. 3. **An approval record per gated action** — the human-oversight artefact for Article 14. 4. **An export envelope** — a portable hand-off format so evidence can leave LumenFlow without losing its integrity proof. These are not a substitute for a full Article 12 conformity assessment, nor for a Notified Body review where one is required. They are the operational substrate that lets a deployer answer the questions the regulator will ask. > **info** > See [Connections: Trusted Compute](/docs/connections-trusted-compute) for > the runnable demo that produces a signed evidence bundle, and > [Autonomy policies and tool-call approvals](/docs/autonomy-policies) for > the Rules and Approvals mechanics that implement Article 14 oversight. --- ## Independently verifiable evidence Category: Security URL: https://lumenflow.cloud/docs/independently-verifiable-evidence ## The problem with self-signed logs Most audit logs are signed by the same vendor that produced them. That is enough to catch accidental corruption, but it does not answer the question a regulator or an enterprise auditor actually asks: *how do I know this record was not written — or back-dated — after the fact?* If the vendor holds the only key, the vendor could in principle re-issue the proof. The trust still rests entirely on the vendor. ## What LumenFlow does differently LumenFlow keeps a tamper-evident evidence chain: receipts from supported governed action paths are folded into an append-only chain with a cryptographic root (a Merkle anchor) per workspace. The chain lets an auditor check the integrity of the receipts supplied for verification; it does not, by itself, prove that every action was captured. An anchor can have two verification layers: 1. **An operator seal** — LumenFlow's own signature over the anchor, proving it came from your workspace and has not changed since it was sealed. 2. **An optional independent external witness** — when configured and reachable, a trusted timestamping authority signs the anchor root using the **RFC 3161** standard. When an anchor has a valid witness token, the token is stored alongside it and can be re-verified **offline** against the authority's published certificates — no access to LumenFlow required. An anchor awaiting a token is not independently witnessed. ## Why the external witness matters For a witnessed anchor, the third-party signature proves the evidence root **existed by the witnessed time**. A later change to that root would fail verification against the token. The proof stands on the witness's signature, not on trusting us. That is the difference between "we say this happened" and "an independent authority confirms this existed by then." ## What it proves — and what it does not For a witnessed root, the token proves **existence by a point in time**; the receipt-chain verifier checks integrity and continuity of the receipts supplied to it. Neither check proves that all actions were captured or that the underlying work was correct or complete. The token also does not substitute for a formal conformity assessment. ## How it fits compliance When present, the external witness adds an independent timestamp to the record used for **EU AI Act Article 12** readiness. Check the anchor's witness status before describing an evidence bundle as independently anchored. See [EU AI Act Article 12 readiness](/docs/eu-ai-act-article-12-readiness) for the full obligation-to-primitive mapping. > **info** > The witness is additive. If the timestamping authority is ever > unreachable, anchors are still sealed and recorded — they are simply > marked as awaiting their independent timestamp rather than being > blocked. An anchor is only ever shown as "independently verified" once > a valid third-party token has been checked. ## Per-receipt hash chain and signature The anchor above protects a periodic, batched root. Underneath it, every individual evidence receipt is also chained the moment it is written: each receipt's hash folds in the hash of the receipt immediately before it, so editing, deleting, reordering, or splicing a receipt breaks a link that is checkable without needing the periodic anchor at all. This hash-chaining happens for every receipt in every workspace, always — there is no configuration that turns it off. On top of that unconditional hash chain, a deployment can optionally enable a cryptographic signature on each receipt using a dedicated signing key. When a signing key is configured, new receipts carry a signature that a third party can check with nothing but the matching public key. When no signing key is configured, receipts are still fully hash-chained — tampering, deletion, and reordering are still detectable — they simply are not individually signed. We say plainly which state a given workspace is in rather than implying every receipt is cryptographically signed by default. ## How a customer or auditor checks this directly Two calls let anyone with API access verify the evidence chain themselves, without taking our word for it: - **Verify the whole chain** confirms the sealed anchor history for a workspace is contiguous and unbroken — no gaps, no rewritten roots. - **Get a proof for one receipt** returns a self-contained inclusion proof showing that a specific receipt is covered by a specific sealed root, which anyone can check independently against that root. Both are available on the evidence API today and are the same mechanisms this article's guarantees are built on. --- ## Workspace AI source: managed inference vs BYOK Category: Model Configuration URL: https://lumenflow.cloud/docs/workspace-ai-source ## Two sources, one decision per workspace | Source | Who runs the model | Who pays | When to use | |--------|--------------------|----------|-------------| | **Managed inference** | LumenFlow | LumenFlow (passed through your plan) | Default for new workspaces; fastest setup | | **Bring your own key (BYOK)** | Your provider account | You, directly | Compliance, custom routing, or you already have credit | Switch in **Settings → Models** (owner or admin only). ## Managed inference LumenFlow operates the model on your behalf using the routing your plan covers. You don't configure providers, keys, or models — Sidekick just works. Managed inference is the default for new workspaces and the fastest way to get from sign-up to first action. ## Bring your own key (BYOK) In BYOK mode you provide a provider API key (Anthropic, OpenAI, or other supported providers) and choose which model to use. Sidekick routes every workspace request through your key. You see the provider's invoicing directly; LumenFlow doesn't mark up the model spend. Set keys in **Settings → API keys**. ## Workspace-level vs per-conversation The AI source is workspace-wide — it controls who pays and which provider is used. Per-conversation model selection (a faster model for quick turns, a stronger model for hard reasoning) happens *within* whichever source you've chosen and doesn't change the source itself. ## Migration Switching sources doesn't replay history. New conversations use the new source; existing evidence stays attached to whichever source ran them. > **info** > See [Model config providers](/docs/model-config-providers) for the supported provider list and [BYOK setup](/docs/model-config-api-keys) for key handling. --- ## Playground and demo workspaces Category: Getting Started URL: https://lumenflow.cloud/docs/playground-overview ## Three surfaces, one Sidekick | Surface | Sign-in | What's there | When to use | |---------|---------|--------------|-------------| | **Public playground** | No | Curated demo scenarios | Quick "what does it do?" preview | | **Demo workspace** | Yes | Seeded data + simulated connector effects | Explore the interface | | **Real workspace** | Yes | Your data + your governance | Actual work | ## Public playground [lumenflow.cloud/playground](/playground) hosts a small set of demo scenarios — drafting an email, triaging an issue, summarising a contract. The playground is signed-out and read-only; nothing you do persists. Use it to see Sidekick's shape before you sign up. ## Demo workspace When you sign up, you can create a demo workspace alongside (or instead of) your real workspace. Demo workspaces: - Have seeded data — sample jobs, fake approvals, mock connectors - Land on **Playground** instead of Dashboard or Sidekick - Carry a "demo" tag in the workspace switcher - Don't count against your plan's billable workspace limit Demo workspaces are real workspaces under the hood — same Sidekick, same evidence trail, same governance. They just isolate seeded data so you can run flows end-to-end without committing to a connector or a real change. ## Real workspaces Your real workspace is where actual work happens. Connect your tools, set autonomy policy, invite teammates, and turn Sidekick loose on your backlog. ## Progression Most teams go: playground (1 visit) → sign up → demo workspace (a few flows) → real workspace (rest of forever). You can keep a demo workspace open as long as you like — it's free to maintain. > **info** > See [Sidekick Overview](/docs/sidekick-overview) for the conversation surface that anchors real workspaces and [What is LumenFlow?](/docs/what-is-lumenflow) for the platform overview. --- ## Microsoft 365 (Outlook Mail, Outlook Calendar, OneDrive, To Do) Category: Integrations URL: https://lumenflow.cloud/docs/integrations-microsoft-365 ## What's covered | Connector | What Sidekick can do | Approval default | |-----------|----------------------|------------------| | **Outlook Mail** | Send, draft, search, summarise email; reply with policy guards | Sends require approval at default trust | | **Outlook Calendar** | Read availability, book meetings, propose times, cancel events | Booking external attendees requires approval | | **OneDrive** | Read, write, share documents and files | Writes use Sidekick's destination defaults | | **Microsoft To Do** | Read tasks, create tasks, update status | Creates auto-approved; bulk changes require approval | ## Setup Each connector authorises separately because they use different Microsoft Graph scopes: 1. Go to **Settings → Connections** 2. Click **Add Connection** and pick the Microsoft 365 connector you want 3. Authorise through Microsoft OAuth (uses your Microsoft 365 account) 4. Confirm scopes — Sidekick asks for the minimum needed for the actions in the table above ## Common patterns ``` Send the kickoff note to the Marketing distribution list and put a 30-minute follow-up on Tuesday afternoon when everyone's free. ``` Sidekick draws on Outlook Mail to compose, Outlook Calendar to find a time, and pauses for approval before sending if your policy requires it. ``` File the Q3 contract in OneDrive under /Legal/2026/Q3 and add a follow-up task to Microsoft To Do tagged "Review by 30 April". ``` OneDrive handles storage; To Do tracks the follow-up. ## Capability boundary These are governed connectors with bounded action sets — they're not a full Outlook or OneDrive client. Specialised mailbox rules, complex calendar delegation, or Microsoft Graph APIs not on the connector's surface need a [Custom MCP server](/docs/integrations-custom-mcp) instead. ## Governance All four connectors respect [autonomy policy](/docs/autonomy-policies) and surface in the [Approvals inbox](/docs/approvals-governance) when a write requires sign-off. Read actions can be auto-approved; sends, bookings with external attendees, and shares default to approval. > **info** > The Outlook Mail connector handles marketing-grade sends through approval; for bulk transactional email use a dedicated provider via [Custom MCP](/docs/integrations-custom-mcp) or [Webhooks](/docs/integrations-webhooks). --- ## HubSpot Category: Integrations URL: https://lumenflow.cloud/docs/integrations-hubspot ## Available today | Action | Description | |--------|------------| | **Find contacts and companies** | Search HubSpot CRM by name, email, domain, or properties | | **Summarise deals** | Read deal stage, owner, last activity, and key properties | | **Log activity** | Add notes, calls, or emails to a contact or deal timeline | | **Create or update records** | Open new contacts, companies, or deals (approval-gated) | ## Setup 1. Go to **Settings → Connections** 2. Click **Add Connection → HubSpot** 3. Authorise through HubSpot OAuth 4. Confirm the HubSpot account and scopes ## Common patterns ``` Pull every open deal in the Q3 pipeline owned by the EMEA team and summarise stage, days-since-last-activity, and next step. ``` ``` Log a note on the Acme Corp deal: "Demo'd v5.3 to procurement, follow-up scheduled Friday." ``` ## Capability boundary The connector targets HubSpot's CRM core (contacts, companies, deals, activities). Marketing Hub automation, custom code workflows, or HubSpot Operations Hub need a [Custom MCP server](/docs/integrations-custom-mcp). ## Governance | Action | Recommended approval | |--------|---------------------| | Read records | Auto-approve | | Log activity | Auto-approve | | Create records | Require approval | | Update records | Require approval | | Bulk changes | Always require approval | --- ## Greenhouse Category: Integrations URL: https://lumenflow.cloud/docs/integrations-greenhouse ## Available today | Action | Description | |--------|------------| | **Search candidates** | Find candidates by name, role, stage, or recruiter | | **Summarise interview kits** | Aggregate scorecard feedback and flag conflicts | | **Move candidates** | Advance or reject candidates (approval-gated) | | **Add notes** | Append recruiter notes or interview summaries | ## Setup 1. Go to **Settings → Connections** 2. Click **Add Connection → Greenhouse** 3. Authorise through Greenhouse OAuth or API token 4. Confirm the Greenhouse account and stage scopes ## Common patterns ``` Show me every Senior Engineer candidate in onsite stage that hasn't moved in 7+ days, with their last interviewer and most recent scorecard. ``` ## Capability boundary The connector covers candidate triage and stage hygiene. Greenhouse Onboarding, custom approvals, or job board integrations are out of scope — use a [Custom MCP server](/docs/integrations-custom-mcp) for those. ## Governance Stage moves and reject decisions always require approval; reads and note additions can be auto-approved. --- ## Agents: operator surface for agents Category: Dashboard Guide URL: https://lumenflow.cloud/docs/dashboard-studio ## Agents is for operators, not consumers Sidekick is the consumer front door. If you are asking for work, approving, or reviewing outputs, stay in Sidekick — see [How LumenFlow looks](/docs/how-lumenflow-looks). Agents is the operator depth surface for job and runtime state. Open it when you need to see the graph, safe actions, outputs, and live runtime activity behind a job. Decisions that need a person's call surface separately in the [coordination inbox](/docs/coordination-inbox). ## What Agents shows - **Job graph** — the live state of an in-flight job's plan, dispatch, and orchestration - **Action rail** — safe operator actions for the focused node, gated by your role and autonomy policy - **Output explorer** — every file, doc, or export the job has produced - **Live overlay** — runtime sessions tracked against the job, refreshed in real time ## Opening Agents The canonical URL: ``` /dashboard//observe/agents?mission=&focus= ``` Both `mission` and `focus` are optional. The URL is also the state — copy it, share it, or land here from a mobile deep-link or a ChannelBridge handoff. ## Action rail The right-hand action rail surfaces safe operator actions for the focused node — pause, resume, retry, reroute, request approval. Risky actions route through your [autonomy policy](/docs/autonomy-policies) and surface in the [Approvals inbox](/docs/approvals-governance). ## Output/artifact explorer Every file Sidekick produced for this job shows up in the explorer with its destination (managed artifacts, OneDrive, GitHub, etc.) and a link to the source of truth. Internal managed artifact links are workspace-scoped review or export links, not public hosting links. See [Outputs, artifacts, and destinations](/docs/outputs-artifacts-destinations) and [Builder destinations](/docs/builder-destinations) for how those destinations get chosen. ## Live overlay The live overlay tracks active runtime sessions against the job and refreshes as Sidekick works. When a session completes, the overlay rolls forward into the output/artifact explorer and the job graph. ## Role gating Agents is open to all workspace members; operator actions on the action rail are gated to owners and admins. > **info** > See [Dashboard Delivery](/docs/dashboard-delivery) for the cross-job view and [Replay](/docs/dashboard-replay) for the post-hoc evidence chain. --- ## Replay: governed replay chain Category: Dashboard Guide URL: https://lumenflow.cloud/docs/dashboard-replay ## What Replay is Replay is the post-hoc audit surface for a job. While [Agents](/docs/dashboard-studio) shows what's happening live, Replay shows what *did* happen — the governed chain correlating a builder job with every delivery step, runtime session, and evidence record it produced. Open at `/dashboard//observe/replays` to see the latest replay chain for the workspace (`/dashboard//observe/replays/` for one in depth). ## What's in a replay chain | Layer | What it shows | |-------|--------------| | **Job** | The intent that started the work | | **Delivery** | The plan, dispatch, and orchestration that turned intent into action | | **Runtime** | The sessions that actually ran — model calls, tool calls, results | | **Evidence** | The artifacts and approvals produced along the way | Together these form a single chain you can step through, share, or export. ## Empty state A workspace with no jobs yet shows an empty state. Replay populates as soon as a builder job has a correlated delivery, runtime, or evidence chain — usually after the first real Sidekick run. ## Replay vs Evidence Vault [Evidence Vault](/docs/evidence-vault) is the full searchable archive across all jobs. Replay is the focused, time-ordered view of a single chain. Use Evidence Vault to find something; use Replay to follow what happened end-to-end. ## Governance Every receipt in the replay chain is hash-chained and tamper-evident. Receipts written since receipt signing was enabled also carry an Ed25519 signature that an auditor can verify with the signing public key; older receipts remain hash-chained but unsigned — see [Traces and evidence](/docs/traces-and-evidence) for the underlying contract. Members and above can view; export and download are role-gated. > **info** > Sidekick's [autonomy policy](/docs/autonomy-policies) determines what writes are recorded — every gated approval, budget check, and tool-call decision lands in the chain. --- ## Yelp Category: Integrations URL: https://lumenflow.cloud/docs/integrations-yelp ## Available today | Action | Description | |--------|------------| | **Look up businesses** | Search Yelp by name, location, or category | | **Read reviews and ratings** | Surface review summaries and aggregate scores | | **Read hours and contact** | Get current hours, phone, address | ## Setup 1. Go to **Settings → Connections** 2. Click **Add Connection → Yelp** 3. Provide a Yelp Fusion API key 4. Confirm the workspace can use the key ## Capability boundary Read-only — Sidekick can't post reviews, claim listings, or modify Yelp data through the connector. For write actions you'd need to operate Yelp's owner-side tools directly. ## Governance Read calls auto-approve. Yelp data is treated as third-party public content; Sidekick won't pass it as canonical fact in policy-driven decisions. --- ## Linear Category: Integrations URL: https://lumenflow.cloud/docs/integrations-linear ## Available today | Action | Description | |--------|------------| | **Find and read issues** | Search issues and read their details | | **Create and update issues** | Open new issues or change existing ones | | **Comment on issues** | Add comments to keep work moving | | **Browse projects** | See the projects issues belong to | ## Setup 1. Go to **Settings → Connections** 2. Click **Add Connection → Linear** 3. Authorize LumenFlow to your Linear workspace 4. Confirm the workspace can use the connection ## Capability boundary Sidekick works with issues, comments, and projects. It does not administer your Linear workspace settings, members, or billing. ## Governance Reads auto-approve. Writes — creating or updating an issue, or posting a comment — route through your workspace's approval policy before Sidekick acts. --- ## Calendly Category: Integrations URL: https://lumenflow.cloud/docs/integrations-calendly ## Available today | Action | Description | |--------|------------| | **List event types** | See the meeting types you offer | | **Check availability** | Look up open times for an event type | | **List scheduled events** | Review what's already on the calendar | | **Create a scheduling link** | Generate a booking link to share | | **Cancel an event** | Cancel a scheduled meeting | ## Setup 1. Go to **Settings → Connections** 2. Click **Add Connection → Calendly** 3. Authorize LumenFlow to your Calendly account 4. Confirm the workspace can use the connection ## Capability boundary Sidekick works with your scheduling — event types, availability, links, and existing events. It does not change your Calendly account settings or billing. ## Governance Reads (event types, availability, scheduled events) auto-approve. Writes — creating a scheduling link or cancelling an event — route through your workspace's approval policy first. --- ## Microsoft Dataverse Category: Integrations URL: https://lumenflow.cloud/docs/integrations-dataverse ## Available today | Action | Description | |--------|------------| | **List and describe tables** | See the tables in your environment and their shape | | **Query and search records** | Run reads and searches across records | | **Fetch a record** | Retrieve a specific record by id | | **Create a record** | Add a new record to a table | ## Setup 1. Go to **Settings → Connections** 2. Click **Add Connection → Microsoft Dataverse** 3. Authorize LumenFlow to your Dataverse environment 4. Confirm the workspace can use the connection ## Capability boundary Sidekick works with tables and records in the connected environment. It does not manage your Dataverse environment, security roles, or Power Platform administration. ## Governance Reads (list, describe, query, search, fetch) auto-approve. Creating a record is a write and routes through your workspace's approval policy before Sidekick acts. --- ## OpenTable Category: Integrations URL: https://lumenflow.cloud/docs/integrations-opentable ## Available today | Action | Description | |--------|------------| | **Find restaurants** | Search restaurants and read their details | | **Check availability** | Look up open tables for a date and party size | | **Hold a slot** | Briefly hold a table while you confirm | | **Create a reservation** | Book a table through the partner flow | ## Setup 1. Go to **Settings → Connections** 2. Click **Add Connection → OpenTable** 3. Authorize LumenFlow to OpenTable 4. Confirm the workspace can use the connection ## Capability boundary Sidekick can search availability and make reservations through OpenTable's partner booking flows. It is not a restaurant-owner management tool. ## Governance Search and availability reads auto-approve. Holding a slot or creating a reservation is a write and routes through your workspace's approval policy before Sidekick acts. --- ## Governed AI compute: campuses and data centres Category: Governance & Policy URL: https://lumenflow.cloud/docs/campus-governed-compute ## Campuses and data centres A campus — a dedicated AI **data centre** (data center / datacenter), **GPU cluster**, or compute facility, whether you operate it or a partner does — is a block of AI compute and its supporting infrastructure. LumenFlow does not own or run the hardware, and it is **not a facility-management (DCIM) system**: it does not manage power, cooling, networking, or hardware provisioning. What LumenFlow adds is the layer most compute lacks: **governance and tamper-evident proof** of the AI work running on the floor — what ran, where, for whom, at what cost, and with what energy and carbon footprint. If you are building, running, or managing a data centre for AI workloads, that governance and proof layer is the part LumenFlow owns. ## The proof bundle For any tenant connected to a campus, LumenFlow can produce a single sealed proof bundle covering four attested records for a time window: - **Utilisation** — GPU-seconds consumed and the cost attributed to them. - **Residency** — proof the work stayed in its pinned region. - **Carbon** — emissions for the work, each figure tagged with how it was derived (measured, modelled, or estimated). - **SLA** — target versus observed service windows, with any breach flagged. The bundle rides the same evidence chain as the rest of LumenFlow: it is cryptographically anchored and passes chain verification before it leaves the system, so a recipient — an auditor, a customer, a regulator — can re-verify it independently. See [Independently verifiable evidence](/docs/independently-verifiable-evidence). ## Exporting the bundle requires a granted approval Exporting a tenant's proof bundle is gated: your workspace needs an active, operator-**granted** export approval before the export runs. Without one, the export request is refused with a structured decline receipt — it never falls back to a partial or redacted bundle. An operator grants the approval once through the standard approvals flow, and the export runs normally afterwards. This is a one-time governance step per workspace, not a per-export prompt. ## Propose, don't actuate LumenFlow's campus role today is to govern and to prove. It surfaces what is happening and produces the evidence for it; it does not directly control physical power, cooling, or scheduling. That boundary is deliberate — it keeps LumenFlow a neutral record over the compute, not an operator of it. ## Residency is enforced, not assumed Campus telemetry enters through the standard events ingest. Events classified as campus work carry a mandatory residency precondition: if the region routing isn't present, the event is refused rather than recorded in the wrong place. Residency is a gate, not a label. ## Power and energy monitoring The same ingest carries the facility's **power and carbon-intensity signals** and its **PUE** (power usage effectiveness), and LumenFlow attributes the power and energy each run uses down to the token — so the proof bundle reports electricity use with measured / modelled / estimated provenance, not a guess (see [Energy and carbon provenance](/docs/energy-carbon-provenance)). LumenFlow monitors and proves this; it never operates the electricity, power, or cooling. ## Routing work to a specific campus Governed proof, residency enforcement, and which connected runner may claim a campus's work are all live. A runner must hold a campus grant from your workspace before it can claim work routed to that site. A runner that only self-declares the capability is refused at claim time. An unenrolled runner cannot pull campus-bound work at all. Ask your LumenFlow contact to set up the grant for your workspace. ## GPU attestation: verified, not just claimed Where a campus node supports confidential-compute attestation, LumenFlow cryptographically verifies the GPU/TEE attestation quote before counting it as verified — it does not take a self-reported claim at face value. A quote that fails verification, or that cannot be evaluated, is labelled unverifiable or self-asserted in the proof bundle, never silently upgraded to verified. The bundle reports which of these applies to each record it covers, so a recipient re-verifying it independently sees exactly how much trust each attestation earned, not a single blended "trusted" flag. ## Propose, never actuate — even here Everything above — routing, capability grants, attestation, energy and residency proof — stops at governance and evidence. LumenFlow does not control facility power, cooling, physical scheduling, or the hardware itself; a campus capability grant authorizes a runner to *claim work*, not to *actuate anything physical*. That boundary holds regardless of what a node's attestation or capability grant says. > **info** > Campus governance is available to connected tenants today. If you operate > or are planning a data centre or dedicated compute site and want governed > proof over the AI compute on it, [reach out](/contact). --- ## Autonomous delivery: from one instruction to finished work Category: Sidekick URL: https://lumenflow.cloud/docs/autonomous-delivery ## From a request to a result Most assistants stop at advice. Sidekick can do the work: given an instruction, it can plan the steps, execute them, and hand back the finished artefacts — a drafted document, a piece of research, a set of changes — with a full evidence trail of what it did. ## You stay in control Autonomous delivery is **opt-in per workspace** and gated: - Sidekick confirms before it commits to executing anything — you see what it intends to do first. - Every run is bounded by your budget and policy. If a step would exceed a limit or trip a rule, it stops rather than pushing through. - Risky actions route to an approval before they run, not after. ## Bigger than one task For larger work, Sidekick can chain a sequence of dependent steps as a plan, checking each step before moving to the next, and streaming progress and evidence throughout. You can follow it live, and you get a complete record at the end. Not all larger work is one straight chain. A big enough ask can branch into several linked pieces of work, some sequential and some independent. Where pieces are genuinely independent, Sidekick can run a bounded, fixed-size set of Agents on them in parallel, rather than working through everything one piece at a time. This is not an open-ended swarm: the number of Agents is capped, each one inherits your workspace's rules and connections rather than getting wider authority of its own, and the branching work still converges into one record — one outcome, one evidence trail, not a scattered set of unconnected runs. See [Governed Sidekick execution](/docs/governed-sidekick-execution) for what the underlying fan-out guarantees. ## It fails loudly, not silently If a step fails or stalls, the run releases its hold, records what happened, and posts a visible failure — within a bounded time. There are no silent dead-ends, and no double-charging for a stuck job. See [Autonomy policies and tool-call approvals](/docs/autonomy-policies) and [Governed Sidekick execution](/docs/governed-sidekick-execution). > **info** > Sidekick only commits to work it can actually deliver. If autonomous > execution isn't available for a request, it says so and still gives you a > useful answer on the first reply, rather than making a false promise. --- ## Hosted app pages: publish a page Sidekick built Category: Sidekick URL: https://lumenflow.cloud/docs/hosted-app-pages ## Publish a page Sidekick built When Sidekick builds you a simple web page — a demo, a prototype, a small utility, a one-off interactive tool — you can ask it to publish that page so you have a real link to share. Sidekick hosts it directly; you don't need to set up a hosting account first. ## How it works 1. Ask Sidekick to build the page (for example, "build me a page that visualizes X" or "make a quick demo of Y"). 2. Ask it to publish or host the page. Sidekick shows you what it's about to make public and asks you to confirm — nothing goes live without your explicit go-ahead. 3. Once you confirm, Sidekick publishes the page and gives you the real link. Anyone with the link can open it. 4. Say "unpublish it" (or "take it down") whenever you want, and the page stops being reachable. Sidekick never tells you a page is live before it actually is — you only get a link once publishing has actually happened, never a guess or a placeholder. ## What this is for Hosted app pages are for small, self-contained, client-side pages: demos, prototypes, one-off utilities, interactive visualizations, simple games, and similar. They're a fast way to share something Sidekick made without leaving the conversation. They are not a general web hosting service. A page that needs a backend, a database, server-side code, or a login system doesn't fit this path — for that kind of full application, Sidekick routes the code to a deployment destination you've connected and approved (your own hosting account) instead of hosting it directly. See [Builder destinations](/docs/builder-destinations) for how that works. ## What's true about every published page - **Revocable, anytime.** You can take a page down whenever you want, and LumenFlow can take a page down too if it needs to. - **Sandboxed.** A published page runs isolated from your workspace — it can't read your data, your account, or anything else in LumenFlow. - **Checked before it goes live.** Every page is checked against a content policy before publishing; a page that fails the check is refused rather than published. - **Checked by LumenFlow, never by your own model key.** The check always runs on LumenFlow's own managed checking, even if your workspace is set up to use your own provider key or a custom endpoint for everyday Sidekick work. Your own key and endpoint are never used to approve a page, and switching your workspace AI source doesn't change how pages are checked. If the managed check isn't available, or its usage limit has been reached, the page is not published rather than being checked some other way. - **No sign-in fields.** Published pages can't collect passwords or sign-in details from visitors. - **Not indexed for search.** Published pages are meant to be shared by link, not discovered through search engines. - **Limited per workspace.** Your workspace has a limit on how many pages can be live at once and how often you can publish. If you're at that limit, Sidekick tells you honestly rather than pretending a publish worked, and gives you a way forward — unpublish an older page, wait, or upgrade. ## Reporting a problem with a published page Every published page carries a way to report it if something looks wrong. Reports go to LumenFlow, not to the person who published it. > **info** > Saving something in LumenFlow and publishing it are different actions. See > [Outputs, artifacts, and destinations](/docs/outputs-artifacts-destinations) > for how managed artifact links, hosted app pages, and connected > deployments differ. --- ## LumenFlow on mobile Category: Getting Started URL: https://lumenflow.cloud/docs/mobile-app ## Governed work in your pocket The LumenFlow mobile app is not a read-only companion. It carries the same capabilities as the web dashboard: start work, follow it live, review evidence, approve or decline pending actions, and resolve issues — all from your phone. **Mobile beta — iOS only.** Android is coming soon, following the iOS rollout. ## What you can do - Open a workspace and chat with Sidekick. - See jobs and their status as they run. - Act on approvals from the notification itself — the human-in-the-loop step works on mobile. - Review the evidence and proof for completed work. ## Getting the app The iOS beta is rolling out through TestFlight. Installation options are on the [download page](/download), which always shows the current way to join for your platform. > **info** > Approvals on mobile carry the same governance weight as on the web — the > same policies, the same evidence. Approving on your phone is not a > shortcut around the rules. --- ## LumenFlow Desktop Category: Getting Started URL: https://lumenflow.cloud/docs/desktop-app ## A desktop home for governed work, in beta LumenFlow Desktop wraps your workspace in a desktop shell, built to sit alongside your work rather than in a browser tab you lose. It's a shell around the same web workspace, not a separate app with its own logic, so policies, approvals, and evidence stay identical to what you see in the browser. **Desktop beta — Linux only.** macOS and Windows builds are pending code-signing and haven't cleared platform QA yet. ## What it adds - **Global launcher** — a system-wide hotkey opens a command bar from anywhere, so you can start or find work without switching windows. - **System tray** — LumenFlow stays available in the background with quick access. - **Native notifications** — approvals and job updates arrive as OS notifications you can act on. - **Deep links** — links open straight to the right workspace, job, or approval. ## Getting it The Linux build (AppImage or .deb) is unsigned while in beta and available on the [download page](/download), which shows the current install option and availability for your operating system. See [Desktop and mobile surfaces](/docs/desktop-mobile-surfaces) for how the apps connect to your workspace. --- ## Organization-wide observability Category: Developer Guide URL: https://lumenflow.cloud/docs/org-observability ## One view across every workspace A single workspace shows you its own work. An organization running many workspaces needs the view across all of them. LumenFlow provides an org-level observability surface backed by an organization-scoped service token. ## What it shows Derived from real activity across your workspaces: - **Work** — what is in flight, with human-readable titles and resolved owners. - **Dispatch** — how work is distributed across lanes and agents. - **Events and telemetry** — a live feed of governed activity. - **DORA metrics** — delivery throughput and stability across the org. ## Role-scoped, read-only The surface is role-aware: an executive view, a delivery view, and an engineering view each show the right altitude of detail. The org token is scoped to observation — it does not grant write access to the underlying workspaces. > **info** > This is how a parent organization, or an external consumer of your work, > integrates a roll-up of LumenFlow activity into its own reporting without > touching individual workspaces. --- ## Bring your own compute (BYOC) Category: Developer Guide URL: https://lumenflow.cloud/docs/bring-your-own-compute ## Your compute, governed Bring-your-own-compute (BYOC) lets governed work run on infrastructure you own — a developer machine, your own servers — while LumenFlow's control plane still sets the rules and keeps the record. ## How it works 1. The cloud issues a governed **authorization envelope** for the run: which capabilities are allowed, the budget, a kill switch, and how the work is confined. 2. A local runner executes inside that envelope. 3. Each tool call streams evidence and cost back to the cloud, so the work is as auditable as anything run in the hosted runtime. ## Why use it - Keep data and execution on your own hardware for residency or security reasons. - Use spare or specialised local compute while keeping central governance. - Prove what ran locally with the same evidence chain as everything else. ## Nothing to expose Your machine connects *outward* to LumenFlow — it pulls work, then reports back. LumenFlow never connects in to your machine. You don't open a port, forward anything, or change a firewall rule, and that stays true whether you connect one laptop or a whole campus of machines. A runner works behind NAT, a corporate firewall, or an air-gapped switch with only outbound HTTPS. ## Your keys stay in the cloud When you bring your own model for coding work, LumenFlow's cloud uses it to plan the work and your machine carries the plan out. Your model API keys are held by the cloud and are never sent to your machine — so you can use your own model without spreading credentials onto local hardware. ## Billing on your own hardware Your infrastructure cost is your own — LumenFlow never marks it up. What LumenFlow bills is the governance plane that runs on top of it: admission, the authorization envelope, evidence capture, and approvals. Each plan includes a monthly allowance of governed-execution time on your own hardware (this is compute time, not AI usage), with metered overage beyond it on paid plans. ## It runs the whole loop, safely For a coding task, your runner does more than run isolated commands — it works the task end to end: it reads the relevant files, makes edits, runs your tests and gates, and tries again — using the failed gate's output to fix the next attempt — until everything passes, then opens a branch and pull request. Every step runs inside an on-machine sandbox: file writes, commands, and network access from governed steps are confined to a declared working directory and enforced by your operating system, not dependent on LumenFlow's cloud to hold the line. See [Connected Compute](/docs/connected-compute) and [Connected-Runtime Enrollment](/docs/connected-runtime-enrollment) to connect a runner. --- ## Federation: governed agents on your own network Category: Developer Guide URL: https://lumenflow.cloud/docs/federation-private-network ## Governance across a boundary Some teams cannot send work to a hosted runtime — the agents need to run inside a private network, next to internal systems and data. Federation is the architecture for that: the agents run on your side; the LumenFlow control plane still governs them. ## What stays where - **On your network:** the agent execution and the systems it touches. - **In the control plane:** policy, approvals, identity, and the evidence record. The two connect over a governed link, so you get private-network execution without losing central oversight or the audit trail. ## When to use it vs the hosted runtime - Use the **hosted runtime** when work can run in LumenFlow's cloud — it is the simplest path. - Use **federation** when execution must stay inside your network for data-residency, security, or connectivity reasons. See [Connected-Runtime Enrollment](/docs/connected-runtime-enrollment) and the [Connected Runtime](/docs/connected-runtime-reference-bridge) for setup. --- ## Energy and carbon provenance Category: Governance & Policy URL: https://lumenflow.cloud/docs/energy-carbon-provenance ## Energy you can trace, not just estimate Carbon reporting for AI is usually a blended estimate. LumenFlow goes finer: where the signals exist, it attributes energy consumption (in joules) per compute run, and even across the phases of a model call, then derives carbon from that. ## Monitoring power and electricity For a governed compute campus, LumenFlow ingests the facility's **power and carbon-intensity signals** and its **PUE** (power usage effectiveness), and attributes the **power draw and energy each compute run uses** — in joules, down to the individual token and the prefill/decode phases of a model call. The result is an auditable picture of electricity use per tenant, per workload, and per run, instead of a single monthly figure. The boundary holds: LumenFlow **monitors, attributes, and proves** power and energy — it does not operate the electricity, power, or cooling itself (see [Governed compute campuses](/docs/campus-governed-compute)). ## Provenance is part of the number Every energy and carbon figure carries a **provenance tier**: - **Measured** — derived from real signals from the compute. - **Modelled** — computed from a defensible model where direct measurement isn't available. - **Estimated** — a coarser fallback. Reporting the tier alongside the figure is the point. An auditor or sustainability lead can see which numbers are grounded in measurement and which are approximations, instead of being handed one opaque total. ## Where it comes from Energy provenance is strongest for compute LumenFlow has signal into — dedicated campus compute and connected runners — and rides the same evidence chain as the rest of your records, so the figures are part of the verifiable trail. See [Governed compute campuses](/docs/campus-governed-compute). > **info** > A measured figure and an estimated figure are never presented as the > same thing. --- ## Your inference wallet Category: Billing URL: https://lumenflow.cloud/docs/inference-wallet ## How managed inference is billed Managed AI usage draws down a per-workspace **inference wallet** of prepaid credits. Governed work also carries a small governance fee on top. If you bring your own provider key (BYOK), your provider bills the model usage. For a proxied BYOK call, only the governance fee for that call is debited from the inference wallet. If your workspace has an inference wallet, the workspace billing surface shows its balance. Plan details are in [Plans & Pricing](/docs/billing-plans-pricing). ## Managing your wallet - **Top up** — buy credits in the fixed amounts offered at checkout. A minimum top-up applies. - **Check your balance** — the workspace billing surface shows current credit and recent usage. - **Set limits** — budgets and alerts let you cap spend and get warned before you hit it. See [Budgets & Alerts](/docs/billing-budgets-alerts). ## When credits run low If a workspace's wallet is empty, managed AI usage — including Sidekick chat that relies on managed inference — pauses until you top up. Work that doesn't need managed inference is unaffected, and topping up resumes it immediately. See [Billing Overview](/docs/billing-overview), [Plans & Pricing](/docs/billing-plans-pricing), and [Workspace AI source](/docs/workspace-ai-source) for managed vs BYOK. --- ## Governed CI/CD pipelines Category: Developer Guide URL: https://lumenflow.cloud/docs/governed-cicd ## Governance in the pipeline Pipelines are where a lot of automated change actually happens — and often where the audit trail goes dark. LumenFlow closes that gap with a first-party CI/CD action. ## What it does Dropped into a GitHub or GitLab workflow, the action can: - Run governed checks as part of the pipeline. - Execute sandboxed tasks under the same policy and budget rules as the rest of LumenFlow. - Emit evidence for what ran, so the pipeline's actions land on the same verifiable record as everything else. ## Why it matters Your build and delivery automation becomes governed work like any other — same policies, same approvals where needed, same evidence chain — instead of a separate, unaudited system. See [Gates and Policy Enforcement](/docs/gates-and-policies) and [Delivery Orchestration](/docs/delivery-orchestration). --- ## Standards-portable evidence (OpenTelemetry) Category: Developer Guide URL: https://lumenflow.cloud/docs/otel-portable-evidence ## Evidence that travels A record is only as useful as the tools that can read it. LumenFlow exports its evidence in **OpenTelemetry** agent-tracing semantic conventions — an open standard — so your existing observability stack can ingest it directly. ## What that means for you - Pull LumenFlow's governed-agent traces into the platform you already use — Datadog, Grafana, or any OpenTelemetry-compatible backend. - Correlate governed agent activity with the rest of your system telemetry in one place. - Avoid lock-in: the evidence is in a portable, standards-based shape, not a proprietary format you can only read inside LumenFlow. See [Traces and Evidence Chains](/docs/traces-and-evidence) and the [Observe Dashboard](/docs/observe-dashboard). --- ## Objectives Category: Dashboard Guide URL: https://lumenflow.cloud/docs/objectives ## What Objectives is Objectives is a review page for the outcomes you've delegated to Sidekick in conversation. When you ask Sidekick to take on a larger piece of work, it becomes an objective you can track here, separate from the moment-to-moment chat. Objectives are created and updated by talking to Sidekick, not by filling in a form on this page. Ask Sidekick for what you need, and it appears here for workspace-level review. ## Where to find it Open Objectives at `/dashboard//objectives`. Each row shows: - **Title** — what the objective is - **Priority** — P0 (most urgent) through P4 - **Status** — pending, in progress, blocked, paused, done, or cancelled - **Last updated**, and a due-date horizon if one was set - **Success criteria** — how you and Sidekick will know it's done ## Objective detail Open an objective to see its full success criteria, any constraints Sidekick is working within, and a free-text progress note describing where things stand. An empty workspace shows "No delegated objectives yet" until the first one is created through chat. > **info** > Objectives is a review surface, not a task editor. To create, change, or cancel an objective, ask Sidekick directly — see [Delegating tasks](/docs/delegating-tasks). ## Ask Sidekick directly You can also work with objectives entirely from chat: ask "what have I delegated" or "what are my objectives" for the current list, and "cancel that" (naming the objective) to stop Sidekick's standing work toward it. Sidekick confirms before cancelling, and cancelling something already cancelled is a safe no-op — it just tells you the current state. --- ## Coordination inbox Category: Governance & Policy URL: https://lumenflow.cloud/docs/coordination-inbox ## What the coordination inbox is When two automated actions conflict, or a rule decides a person should weigh in before work continues, LumenFlow raises a **decision case**. The coordination inbox is where those cases land for review. Open it at `/dashboard//coordination/inbox`. ## What you'll see Each decision case shows: - **The triggering message** — the request that raised the case, and who sent it - **Recipients** — everyone the case was routed to, with a per-person delivery status: awaiting, delivered, acknowledged, or rejected Filter the inbox by state, recipient, or urgency. The states you'll see are **Waiting on**, **Blocked by**, **Answered not acked**, **Needs a policy call**, and **Resolved**. ## Acknowledging a case Open a case and click **Acknowledge** to record that you've seen it and accept the routed decision. Acknowledgement is logged against your account and the case's history. ## Coordination rules Workspace owners and admins author the rules that decide which conflicts resolve automatically, which fall back to a safe default action, and which get raised to a person, at **Coordination → Playbooks** (`/dashboard//coordination/playbooks`). Other workspace members can view the active rules but not edit them. ## Ask Sidekick directly You don't have to open the inbox to check what's waiting. Ask Sidekick "what's waiting on me" or "what needs a decision from another agent" and it lists the open cases with their state. From the same conversation you can respond too — acknowledge a case, reject it with a reason, or counter it with a different proposal. Sidekick only accepts your response as the identity a case is actually waiting on, the same rule the inbox's Acknowledge button enforces. > **info** > See [Approvals & governance](/docs/approvals-governance) for how decision cases relate to the broader approvals model. --- ## Shadow-agent inventory Category: Governance & Policy URL: https://lumenflow.cloud/docs/shadow-agent-inventory ## What we see, and what we govern Shadow-agent inventory is a bounded inventory over the signals LumenFlow can observe: its own governed runtimes, agents that describe themselves, and telemetry you send it. It is not a tenant-wide scan, so an empty list means nothing has been observed here, not that nothing exists — and it never acts on its own. Open it at `/dashboard//observe/agents/shadow`. Only workspace owners and admins can see this page. ## The three groups - **Governed** — activity running under LumenFlow's own governance - **Observed, not governed** — activity LumenFlow can see but doesn't control - **Reviewed and set aside** — entries an admin has already actioned Each entry shows a state (Registered, Discovered, Suspected, Ignored, or Remediated), a confidence level where applicable, its source, when it was first and last seen, and a retention expiry. ## What you can do This is a confirm-only inventory, not a control surface — there's no start, stop, or pause action for the underlying activity. An admin can only record a judgement about an entry: - **Ignore** — set an entry aside - **Restore** — undo an ignore - **Mark remediated** — record that the activity has been addressed - **Not an agent** — mark a false positive so it stops resurfacing > **info** > This inventory complements the [Audit & Compliance](/docs/bridges-audit-compliance) trail — it's about visibility into agent-like activity, not a replacement for approvals or policy. --- ## Compliance export Category: Security URL: https://lumenflow.cloud/docs/compliance-export ## Two export surfaces LumenFlow has two related compliance-export surfaces: a workspace-level promise summary, and an org-level audit-trail export. ### What we promise (workspace level) Open **Observe → Compliance** at `/dashboard//observe/compliance` to see, in your compliance pack's own terms: - **Active promises** — backed by a shipped control, sold today - **Roadmap, not sold** — explicitly disclosed as not yet available - **Explicitly refused** — claims the pack will never make, such as formal certification This page also shows your current data-retention floor and whether legal hold is engaged. Use **Export CSV** or **Export bundle (JSON)** to download a summary of what's on screen. This is a workspace owner/admin action. ### Audit-trail export (org level) Open the Trust page at `/dashboard/trust` to download a CSV or JSON export of the platform audit-event trail — who did what, when, across a chosen scope (platform, org, workspace, or all): pick a scope and a format, then **Download audit export**. This export is a plain projection of the audit log, not a signed artifact. For the cryptographic properties LumenFlow does provide, see [Independently verifiable evidence](/docs/independently-verifiable-evidence): every evidence receipt is hash-chained, and receipts written since per-receipt signing was enabled also carry an Ed25519 signature that can be checked against the published public key. ## Selecting a compliance pack GDPR, HIPAA, finserv, EU AI Act, and sovereign-residency packs are available per workspace. Select or deselect packs on **Dashboard → Trust** — each change is recorded on the platform audit trail. Packs are readiness postures for your own audit programme, not a certification badge. ## Article 12 auditor pack From the same Trust dashboard, download an **Article 12 auditor pack** for a workspace — one on-demand evidence pack for EU AI Act Article 12 record-keeping. Generation can fail closed (for example when signing is not configured); the button reports that inline rather than inventing a pack. > **info** > See [Trust Centre](/docs/trust-centre) for the public and console trust surfaces, [Compliance & Privacy](/docs/security-compliance) for the broader privacy and data-handling picture, and [Audit & Compliance](/docs/bridges-audit-compliance) for what the audit trail records. --- ## Connect to LumenFlow via MCP Category: Developer Guide URL: https://lumenflow.cloud/docs/mcp-server-connection ## LumenFlow as an MCP server LumenFlow can act as a server for MCP-compatible AI tools — for example an AI coding assistant — so they can query your workspace as a connected data source. ## Endpoint and authentication ``` POST https:///api/v1/mcp ``` Authenticate with a workspace API key as a bearer token: ``` Authorization: Bearer ``` Generate or revoke API keys from your workspace settings — see [API reference](/docs/api-reference). The endpoint supports standard MCP discovery (`initialize`, `tools/list`, `resources/list`), so a compliant MCP client can connect and discover what's available without extra configuration on your end. ## What's available today One tool is wired up: a read-only list of your workspace's delivery programs, each with its ID, title, status (active, completed, or cancelled), created and completed dates, and a progress figure. You can optionally filter by status. The tool is read-only and never makes changes to your workspace. More tools will be added to this surface over time. > **info** > There's no in-dashboard "Connect" button for this yet — point your MCP client at the endpoint above with a workspace API key to get started. --- ## Which credential is for what Category: Security URL: https://lumenflow.cloud/docs/connected-compute-credentials ## One secret per job, not one secret for everything LumenFlow deliberately keeps identity narrow: the credential that lets you click around the dashboard cannot pair a machine, the code that pairs a machine cannot run your CI pipeline, and none of them can stand in for each other. If something asks you to reuse one of these where a different one belongs, that's a sign to stop and check, not a shortcut to take. | Credential | What it's for | Who or what holds it | Lifetime | |---|---|---|---| | **Dashboard session** | Acting as yourself in the browser — chat, settings, approvals | Your signed-in browser | As long as your session stays valid | | **CI / workspace API key** | The strongest credential: a CI job or self-hosted automation calling the control plane or Sidekick API as a service | Your CI secrets store, or a git-ignored local env file | Until you rotate or delete it | | **Provider (tool) installation** | The connection between your workspace and an external tool — email, chat, calendar, tickets | Held by LumenFlow, scoped to that one provider and workspace | Until you disconnect it or the provider revokes access | | **Encrypted connector or model secret (BYOK)** | An API key you bring for a model provider, or a custom connector | Stored encrypted, workspace-scoped | Until you replace or remove it | | **Node identity** | Your workspace's record of one paired Linux or Windows machine — what it is, what it's allowed to claim | Held in your workspace, not on the machine | As long as the machine stays paired | | **Pairing exchange (single-use code)** | Turning "an owner approved this in a browser" into "this exact machine is authorized" | Shown once to the owner/admin who mints it | Minutes — then it expires, used or not | | **Runtime credential** | The durable secret the paired machine itself presents on every request | Stored locally on that machine only | Durable, until rotated or revoked | | **Assignment lease** | Proof that a machine currently owns one specific unit of work | Held only in the machine's memory for that one assignment | Seconds to minutes — the life of the assignment | ## Rotation and revocation - **Dashboard session** — sign out and back in; a workspace admin can end sessions for everyone. - **CI / workspace API key** — regenerate it from **Settings → Advanced**. The old key stops authenticating within moments. Delete it the same way if you no longer need it. - **Provider installation** — disconnect and reconnect from the tool's entry in workspace settings. You can also pull access from the provider's own app-management page at any time. - **Encrypted connector/model secret** — paste a new key over the old one in Settings; the previous value is discarded immediately. You can also revoke it at the provider's own dashboard. - **Node identity and runtime credential** — pair again for a fresh identity, or use the machine's row on the workspace **Compute** page to issue a new runtime credential (the old one is invalidated the moment the new one is issued), drain it (stop new work, let anything in flight finish), quarantine it (stop it claiming anything at all while you investigate), or revoke it outright. - **Pairing exchange code** — it consumes itself the instant a machine exchanges it. An unused one simply expires; mint a fresh one if you need to retry. - **Assignment lease** — not something you rotate by hand; a new one is issued with every claim, and releasing, failing, or completing the assignment ends it. ## Prohibited storage and transport None of these should ever appear as a literal command-line argument you'd retype from shell history, in a repository file, in a chat message, in a support ticket, or copied onto a second machine: - The **CI/workspace API key** belongs in a CI secrets store or a git-ignored local env file — never a bare `export TOKEN=...` you'd type interactively, and never inside `workspace.yaml` or any file you'd commit. - The **runtime credential** belongs in the local file the pairing exchange writes on that one machine — never copied to a second machine, pasted into a ticket, or committed. - The **pairing code** is shown once, in the browser, to the person pairing the machine. Treat it as burned the moment it appears anywhere else — a chat thread, a screenshot, a shared document — and mint a new one. - **Encrypted connector and model secrets** never need to be pasted into a conversation with Sidekick itself; the settings page is the only place that should ever ask for one. If a request, a ticket, or a piece of software asks you to hand over one of these credentials somewhere other than its own settings page, that request is wrong regardless of how official it looks — pause and verify before you comply. --- ## Connect a Linux machine as a Connected Compute node Category: Developer Guide URL: https://lumenflow.cloud/docs/connected-compute-linux-setup ## What you're setting up A Connected Compute node is a machine you control that pulls governed work from your workspace, executes it under your workspace's policy, and reports evidence back — your compute, LumenFlow's governance. Linux is the preferred production posture: it gets LumenFlow's strongest sandboxing by default. See [Connected Compute](/docs/connected-compute) for the concept and [Which credential is for what](/docs/connected-compute-credentials) for how this fits alongside your other workspace credentials. ## Prerequisites - A recent Node.js runtime available on the machine (the current setup path runs a small bootstrap script with `node`). - Outbound HTTPS access to your workspace's cloud endpoint. Nothing needs to listen for inbound connections — see **Firewall and outbound networking** below. - Workspace owner or admin access, to generate the credential this machine will use. ## Step 1 — Get your machine's credential Open your workspace's **Compute** page and use **Runner setup**. This mints a one-time credential for this workspace and generates the exact commands for your platform — connect, doctor, and a one-iteration run. Copy the generated command directly from the page; don't reconstruct it from an old ticket, chat transcript, or a command a teammate pasted for a different workspace, since the credential and directory are specific to this pairing. The commands the page shows you run through Node, fetching a signed bootstrap from your workspace's own API — they don't require installing a package globally or reaching the npm registry. > **warning** > The credential is shown once. Don't paste it into a ticket, a chat > message, or a shared document — treat it as burned if it ever appears > anywhere outside that one command, and re-run **Runner setup** for a fresh > one. ## Step 2 — Connect Run the generated **connect** command in a terminal on the Linux machine. It writes a local credential file (not printed to your screen after this step) and registers a runner session with your workspace. ## Step 3 — Doctor Run the generated **doctor** command. It reports, in plain terms: | What doctor checks | What it means | |---|---| | Credential file present | The local credential from Step 2 was found and is readable | | Runtime claim admission | Your workspace accepted this machine's request to claim work | | Runner session | The session id your workspace is tracking for this machine | | Capability probe | What this machine advertised it can do | | Confinement posture | The isolation level LumenFlow detected on this machine | | Energy sensor | Whether measured energy readings are available on this machine, or only modeled/estimated | | Work availability | Whether there's eligible work queued for this machine right now | `no eligible work` is a healthy idle state, not an error — it means the machine is connected and polling, and there's simply nothing queued for it. ## Is this machine ready to run work? Your workspace's **Compute** page shows more than whether this machine is connected — it shows whether it can actually run work right now. A machine that's polling but can't yet do anything useful (for example, waiting on capability approval, or missing something doctor's report flagged) is shown as **not ready yet**, with a plain-language reason and the setup step that fixes it, right next to its connection status. A machine that's cleared every check is shown as **ready to run work**. If you ever see this machine listed as connected but not ready, the reason shown on the Compute page tells you exactly what to do next — usually approving a capability, installing something doctor named, or re-running Step 2 for a fresh session. When the reason is about a missing approval, the Compute page also lists what this machine asked to do next to what you've already approved for it, side by side, so you can see exactly what to approve (or leave refused) without switching pages. This machine's own compute never needs a prepaid credit top-up — you're running it on your own hardware, so there's no compute-credit wallet to fund. Work it runs is measured against your plan's monthly execution allowance instead: free plans stop admitting new work once that allowance is used up for the month (the Compute page tells you when, and that it resets next billing period), and paid plans simply keep running past the included allowance. ## Firewall and outbound networking This machine only ever calls out to your workspace's cloud endpoint over HTTPS — it polls for work, then reports back. LumenFlow never opens a connection into your machine. You don't need to open an inbound port, configure port forwarding, or carve out a firewall exception beyond normal outbound HTTPS, whether you're pairing one laptop or a whole fleet. ## Confinement Linux gets LumenFlow's production-default sandboxing: work runs isolated from the rest of the machine using your operating system's own isolation primitives, not something LumenFlow has to hold together from the cloud side. A machine that can't offer that isolation is treated as reduced-posture and kept off privileged work — doctor's confinement line tells you which state your machine is in. ## Local models on this machine If you point this machine at a model you're running locally (for example an OpenAI-compatible server on `localhost`), your workspace's model configuration needs the matching endpoint and model id, and the endpoint needs to be reachable from this machine specifically. Doctor's report includes whether that endpoint is reachable. LumenFlow never silently substitutes a different model when your configured local one is unreachable — it holds or refuses the assignment instead. ## Drain, quarantine, and remove this node - **Drain** — stop the machine from claiming new work while letting anything already in progress finish or fail safely. Use this before planned maintenance. - **Quarantine** — stop the machine claiming anything at all, immediately, while you investigate something unexpected. - **Revoke** — invalidate this machine's credential outright. A revoked machine fails closed on its next request. - **Remove the local install** — stop the running process and delete the local credential file. Your workspace keeps the historical evidence for work this machine already did; removing the local files doesn't erase that record. These actions are available today through your workspace owner/admin — ask us if you don't see a control for one of them yet on the machine's row in the **Compute** page, and we'll help. --- ## Connect a Windows machine as a Connected Compute node Category: Developer Guide URL: https://lumenflow.cloud/docs/connected-compute-windows-setup ## What you're setting up A Connected Compute node is a machine you control that pulls governed work from your workspace, executes it under your workspace's policy, and reports evidence back — your compute, LumenFlow's governance. See [Connected Compute](/docs/connected-compute) for the concept and [Which credential is for what](/docs/connected-compute-credentials) for how this fits alongside your other workspace credentials. ## Prerequisites - A recent Node.js runtime available on the machine (the current setup path runs a small bootstrap script with `node`). - Outbound HTTPS access to your workspace's cloud endpoint from a PowerShell or terminal session. Nothing needs to listen for inbound connections — see **Firewall and outbound networking** below. - Workspace owner or admin access, to generate the credential this machine will use. ## Step 1 — Get your machine's credential Open your workspace's **Compute** page and use **Runner setup**, choosing Windows. This mints a one-time credential for this workspace and generates the exact PowerShell commands for this machine — connect, doctor, and a one-iteration run. Copy the generated command directly from the page rather than adapting a Linux command by hand: Windows PowerShell and POSIX shell commands are never meant to be mixed in the same command block. > **warning** > The credential is shown once. Don't paste it into a ticket, a chat > message, or a shared document — treat it as burned if it ever appears > anywhere outside that one command, and re-run **Runner setup** for a fresh > one. ## Step 2 — Connect Run the generated **connect** command in PowerShell on the Windows machine. It writes a local credential file (not printed to your screen after this step) and registers a runner session with your workspace. ## Step 3 — Doctor Run the generated **doctor** command. It reports, in plain terms: | What doctor checks | What it means | |---|---| | Credential file present | The local credential from Step 2 was found and is readable | | Runtime claim admission | Your workspace accepted this machine's request to claim work | | Runner session | The session id your workspace is tracking for this machine | | Capability probe | What this machine advertised it can do | | Confinement posture | The isolation level LumenFlow detected on this machine | | Energy sensor | Whether measured energy readings are available on this machine, or only modeled/estimated | | Work availability | Whether there's eligible work queued for this machine right now | `no eligible work` is a healthy idle state, not an error — it means the machine is connected and polling, and there's simply nothing queued for it. ## Firewall and outbound networking This machine only ever calls out to your workspace's cloud endpoint over HTTPS — it polls for work, then reports back. LumenFlow never opens a connection into your machine. You don't need to open an inbound port, configure Windows Firewall for an inbound rule, or forward anything beyond normal outbound HTTPS. ## Confinement and energy on Windows Windows machines run at a reduced isolation posture by default compared to Linux — doctor's confinement line reports which one your machine actually has, and reduced-posture machines are kept off privileged mutation work. Measured energy readings are also not currently available on Windows through the diagnostic setup path (this is most visible on AMD/Ryzen hardware): energy for assignments on this machine shows as modeled or estimated rather than measured until an admitted Windows sensor ships. Don't treat a modeled or estimated figure as a sensor reading. ## Local models on this machine If you point this machine at a model you're running locally (for example an OpenAI-compatible server on `localhost`), your workspace's model configuration needs the matching endpoint and model id, and the endpoint needs to be reachable from this machine specifically. Doctor's report includes whether that endpoint is reachable. LumenFlow never silently substitutes a different model when your configured local one is unreachable — it holds or refuses the assignment instead. ## Drain, quarantine, and remove this node - **Drain** — stop the machine from claiming new work while letting anything already in progress finish or fail safely. Use this before planned maintenance or a reboot. - **Quarantine** — stop the machine claiming anything at all, immediately, while you investigate something unexpected. - **Revoke** — invalidate this machine's credential outright. A revoked machine fails closed on its next request. - **Remove the local install** — stop the running process and delete the local credential file. Your workspace keeps the historical evidence for work this machine already did; removing the local files doesn't erase that record. These actions are available today through your workspace owner/admin — ask us if you don't see a control for one of them yet on the machine's row in the **Compute** page, and we'll help. --- ## Bringing your own model through OpenRouter Category: Model Configuration URL: https://lumenflow.cloud/docs/byok-openrouter-and-free-models ## OpenRouter as a BYOK source OpenRouter is a supported preset for bringing your own model: add your OpenRouter API key in **Settings → Models**, and LumenFlow talks to it the same way it talks to any OpenAI-compatible provider endpoint. See [API Key Management](/docs/model-config-api-keys) for how the key itself is stored and rotated, and [Workspace AI source](/docs/workspace-ai-source) for how BYOK fits alongside managed inference. ## What's available comes from OpenRouter, live When you add or refresh an OpenRouter connection, LumenFlow asks OpenRouter directly which models your key can currently use, and what each one costs — it doesn't consult a hardcoded list. Every model in that response carries its own live pricing, including whether OpenRouter is currently offering it at no cost. This means: - **The list of available models changes as OpenRouter's catalog changes.** A model present today can be removed, repriced, or replaced by OpenRouter tomorrow, and your workspace's picker reflects that on the next refresh. - **A model marked free today is not a permanent promise.** Providers — OpenRouter included — offer free access to specific models as a time-limited or capacity-limited arrangement, not a standing commitment. LumenFlow surfaces whatever OpenRouter's catalog reports at the moment you look, and nothing in that surface should be read as "this will always be free." - **If OpenRouter's catalog is temporarily unreachable**, LumenFlow shows you the last catalog it successfully fetched, clearly marked as potentially stale, rather than inventing a list. If nothing has ever been fetched successfully, it says so and asks you to try again or enter a model id manually. ## Checking current pricing and limits yourself Because availability and pricing are OpenRouter's to set, the source of truth is always OpenRouter's own live dashboard and documentation, not a number quoted in LumenFlow's docs or by Sidekick in conversation. Refresh the catalog in **Settings → Models** any time you want an up-to-date read before committing a workflow to a specific model. ## BYOK failures are surfaced, never silently swapped If your OpenRouter key stops working, hits a rate limit, or the specific model you configured becomes unavailable, LumenFlow surfaces that failure to you rather than quietly routing your request to a different, possibly paid, model on your behalf. You decide what to do next — pick another model from the live catalog, or fix the key. --- ## Trust Centre Category: Security URL: https://lumenflow.cloud/docs/trust-centre ## Public trust centre The public trust centre at [/trust](/trust) projects the same enterprise readiness model operators see in the product. Every readiness row — evidence vault, compliance export, org-scoped trust posture, SSO, SAML, and SCIM provisioning — comes from real configuration, not marketing literals. Identity-provider rows reflect the public default (not enabled) until your organisation turns them on. Each row is labelled **Live today** or **Planned**. Related public pages: - [/subprocessors](/subprocessors) — versioned register of third-party processors (purpose, location, and transfer safeguard), with 30 days' notice of new processors. The customer [data processing agreement](/legal/dpa) is published alongside it; the change log records every register version. - [/status](/status) — live health of the public API and application database, read from the public health feed. When the feed cannot be reached, every row is marked **Unknown**. This surface does not invent uptime history, a past-incident feed, or a response-time commitment. ## In-product Trust dashboard Signed-in operators use **Dashboard → Trust** (`/dashboard/trust`) for workspace-scoped trust controls: | Control | What it does | |---------|----------------| | **Compliance packs** | Select or deselect GDPR, HIPAA, finserv, EU AI Act, and sovereign-residency packs per workspace. Changes are audited. | | **Data residency** | Entitled workspaces pin a region (eu_west, us_east, us_west, or apac). Unentitled plans see a refusal explanation and cannot save a pin. Cross-region model calls and residency-relevant storage writes are refused with a residency-violation receipt. | | **Article 12 auditor pack** | Download one on-demand evidence pack for EU AI Act Article 12 record-keeping for a chosen workspace. | | **Audit-trail export** | Download a CSV or JSON projection of the platform audit-event trail — unsigned; see [Compliance export](/docs/compliance-export). | ## What these surfaces do not claim - No published support response-time commitment or SLA until one is written into a contract - No certification badge — readiness and export surfaces support your own assurance work; they are not a formal conformity assessment - No invented uptime history or past-incident feed beyond the live health rows on [/status](/status) > **info** > For data-handling detail see [Compliance & Privacy](/docs/security-compliance). For export surfaces see [Compliance export](/docs/compliance-export). For how to contact us see [Getting Support](/docs/troubleshooting-support). --- ## SIEM push recipes (Datadog, Grafana, Sentinel) Category: Security URL: https://lumenflow.cloud/docs/siem-push ## What this configures LumenFlow can push governed-action evidence spans to an OpenTelemetry collector URL your organisation configures. Spans are posted as **OTLP/HTTP JSON** to an HTTPS `/v1/traces` endpoint you choose. Delivery retries on transient failures and lands exhausted attempts in a dead-letter queue that a scheduled drain retries later. Destination URLs must be public HTTPS (private and loopback addresses are refused). A destination outside your organisation's pinned residency region is refused, and a compliance pack that forbids evidence egress blocks configuration entirely. Organisation admins configure the destination with: ``` PUT /api/v1/orgs//evidence-egress ``` ```json { "kind": "otlp", "endpointUrl": "https://collector.example/v1/traces", "headers": { "Authorization": "…" }, "destinationRegion": "eu_west", "status": "active" } ``` `destinationRegion` must be one of `eu_west`, `us_east`, `us_west`, or `apac`. Outbound auth headers are stored encrypted and never returned in list responses. List destinations with `GET` on the same path; remove one with `DELETE ?kind=otlp`. The payload is the closed evidence-span field set only — action name, honest-scope fields, and opaque identifiers such as receipt and workspace ids — never prompts, tool arguments, or credentials. For the standards-portable shape of that evidence, see [Standards-portable evidence (OpenTelemetry)](/docs/otel-portable-evidence). A separate Splunk HTTP Event Collector destination kind is also available on the same API (`kind: "splunk_hec"`). This article covers **OTLP** destinations only. ## Recipe: Datadog 1. In Datadog, create an API key and note which Datadog site your organisation uses. 2. Use Datadog's OTLP traces intake URL for that site — for example `https://otlp.datadoghq.com/v1/traces` (US1) or `https://otlp.datadoghq.eu/v1/traces` (EU). Confirm the exact URL in Datadog's current OTLP intake documentation for your site. 3. Configure LumenFlow with `kind: "otlp"`, that HTTPS URL as `endpointUrl`, header `dd-api-key` set to your Datadog API key, and a `destinationRegion` that matches where the intake lives. 4. If Datadog's intake for your organisation requires protobuf-only or an allowlisted source header your key does not yet carry, place any OTLP/HTTP collector you control on a public HTTPS URL in front: point LumenFlow at that collector, and let the collector re-export to Datadog. ## Recipe: Grafana Cloud 1. In Grafana Cloud, open your stack's **OpenTelemetry** tile and copy the OTLP gateway URL, numeric instance ID, and an access-policy token with traces write permission. 2. Build the full traces URL as `https://otlp-gateway-.grafana.net/otlp/v1/traces` (use the host Grafana shows for your stack — the region segment varies). 3. Configure LumenFlow with `kind: "otlp"`, that URL as `endpointUrl`, and an `Authorization` header using HTTP Basic auth: username = instance ID, password = the token (send `Authorization: Basic `). 4. Set `destinationRegion` to the Grafana Cloud region that hosts the gateway. Grafana Cloud's OTLP gateway accepts OTLP/HTTP JSON on that path. ## Recipe: Microsoft Sentinel 1. In Azure, enable OpenTelemetry intake for the Log Analytics workspace your Microsoft Sentinel instance uses (Application Insights OTLP connection info, or a Data Collection Endpoint plus Data Collection Rule with the Microsoft OTLP traces stream). Copy the **traces** OTLP URL Azure shows — it ends in `/otlp/v1/traces`. 2. Azure Monitor authenticates OTLP with a short-lived Microsoft Entra bearer token. LumenFlow stores static outbound headers and does not refresh Entra tokens, so run a small OTLP/HTTP collector you control on a **public HTTPS** URL: that collector refreshes the Entra token and forwards to Azure's traces URL; LumenFlow points at your collector. 3. Configure LumenFlow with `kind: "otlp"`, your collector's HTTPS `/v1/traces` URL as `endpointUrl`, any headers your collector requires, and a `destinationRegion` matching the Azure region of the Data Collection Endpoint. 4. In Microsoft Sentinel, query the connected workspace for the OpenTelemetry spans your collector forwarded — the exact table names follow Azure Monitor's OTLP intake (for example OTelSpans), not a LumenFlow-specific schema. ## What this does not do - It does not invent a native Datadog, Grafana, or Sentinel transport — every recipe uses the same OTLP destination kind. - It does not export message content, prompts, tool arguments, or secrets. - It does not bypass residency pins or a compliance pack that forbids evidence egress. > **info** > See [Standards-portable evidence (OpenTelemetry)](/docs/otel-portable-evidence) for the portable evidence shape, [Independently verifiable evidence](/docs/independently-verifiable-evidence) for receipt verification, and [Trust Centre](/docs/trust-centre) for residency and compliance controls that gate this egress. ---