Getting Started

Architecture Overview

How Orkestia splits into a control plane that orchestrates and a customer cloud that executes, where the MCP server sits, and the privacy boundary between the planes

TL;DR

Two planes. The Orkestia control plane decides what should happen and records what did. Your cloud is where the work runs.
One engine, several doors. Console, REST and SDKs, DGI, and the MCP server all drive the same event-sourced workflow engine.
The MCP server is the assistant door. It exposes discover, start, watch, and recover tools, plus rule resources and prompt templates, scoped to your org by your token.
Async is one path. Long-running steps advance through the engine's transition bus. Nothing is fire-and-forget.
The boundary is the point. Orkestia stores state and telemetry. Compute, resources, and data stay in your accounts.

APIs, the workflow engine, the async transition bus, the MCP server, DGI, identity, Lumen, and — when you opt in — App Data and App Host. Stores workflow state, telemetry, and the rows of apps that chose the platform data plane. Orchestrates cloud work in your accounts; hosts a site only if you claim one.

Customer cloud (yours)

Where workflows act: runners, provisioned infrastructure, provider APIs. Compute and data stay in your AWS, GCP, Azure, or Kubernetes accounts. You pay the provider directly.

The planes talk over scoped connections you authorize (AWS connections, Cloud connections). The control plane issues instructions and observes outcomes. Your cloud does the work.

How it fits together

Console & apps
SDKs (Node / Python) & REST
AI assistants & agents
Claude, ChatGPT, Cursor, Staff actors
End-users
Sign in with Orkestia
MCP server
mcp.orkestia.dev · tools + rules + prompts
DGI
goal → plan
Core API + Workflow API
auth · RBAC · start · watch
Workflow engine
event-sourced state machine
Transition bus
workflow.transition
Transition consumer
advances long-running runs
Identity & multi-tenancy
Lumen
telemetry + Lumen MCP
Runners
Provisioned infra
Provider APIs
AWS / GCP / Azure / GitHub / …

Console & apps→Core API + Workflow API
SDKs (Node / Python) & REST→Core API + Workflow API
End-users→Identity & multi-tenancy
Identity & multi-tenancy→Core API + Workflow API
AI assistants & agents→MCP server
AI assistants & agents→DGI
DGI→Workflow engine
MCP server→Workflow engine
Core API + Workflow API→Workflow engine
Workflow engine→ long-running steps →Transition bus
Transition bus→Transition consumer
Transition consumer→Workflow engine
Workflow engine→ acts on →Provider APIs
Transition consumer→ acts on →Provider APIs
Provider APIs→Runners
Provider APIs→Provisioned infra
Workflow engine→ transitions →Lumen

Read it left to right. A caller (console, SDK, assistant over MCP, or end-user through @orkestia/auth) reaches an API or the MCP server, which drives the engine. Long-running steps hand off to the transition bus and are advanced by the consumer. Both act on provider APIs in your cloud. Lumen is a separate telemetry API. App Data is the declared app-row store (opt-in). App Host is opt-in hosting on Orkestia's shared pool. Engram is agent memory, and DevKit is the local CLI.

Core components

Component	Plane	Role
Core API	Control	Auth, organizations, RBAC, billing. The front door for the console and SDKs.
Workflow API	Control	Discover, start, watch, and read history for runs. `workflow-api.orkestia.dev`.
Workflow engine	Control	Event-sourced state machine: 3-state pattern, middleware pipeline, plugins, per-run locks.
Workflow libraries	Control	Atomic primitives named `{provider}.{service}.{operation}`, composed DAGs, and the virtual engine that compiles compositions.
Transition consumer	Control	Consumes `workflow.transition` and advances long-running runs out of band.
MCP server	Control	The assistant door at `https://mcp.orkestia.dev/mcp`: tools, rule resources, prompt templates, and an embeddable console.
DGI	Control	Turns a natural-language goal into a validated workflow plan.
Identity	Control	Org members and end-users. Powers "Sign in with Orkestia". Signing keys (nsec) are a separate credential family.
App Data	Control (opt-in)	Declared app rows and serving Postgres. query.orkestia.dev for operators.
App Host	Control (opt-in)	Claimed site on the shared pool: website, process, Nostr Buzz.
Lumen	Control	Telemetry store at `lumen-api.orkestia.dev`, with its own MCP at `mcp-lumen.orkestia.dev`.
Runners and infrastructure	Customer	The compute that runs jobs and the resources workflows provision. In your cloud.

The APIs: the front door

The Core API handles authentication, org scoping, and RBAC. The Workflow API exposes the engine: discover a capability, start a run, watch it, read its history. Callers never talk to the engine raw. The APIs enforce who you are and what you may run before a single transition fires.

The engine: one state machine for everything

Every capability runs on a single event-sourced state machine. A run is the replay of an append-only sequence of transitions, not a row mutated in place. That gives full history and deterministic recovery. Atomic workflows follow PENDING → COMPLETED | FAILED. DAGs orchestrate many such steps. RBAC, validation, and observability live in the engine's middleware, so every run behaves the same no matter how it was started. See Workflows.

The libraries: three tiers of capability

Atomic library
one operation each
Composed library
multi-step DAGs
Virtual engine
compiles compositions
Workflow engine

Atomic library→Composed library
Atomic library→Virtual engine
Composed library→Virtual engine
Virtual engine→ DAG config →Workflow engine
Composed library→Workflow engine

Atomic primitives do one operation each. Composed DAGs chain them. The virtual engine turns an AI-authored or hand-authored composition into validated DAG config the engine runs unchanged. There is no runtime marker distinguishing a compiled composition from any other DAG. See Virtual workflows.

Async: one canonical path

Work that takes time never blocks the caller. The engine publishes a workflow.transition message; the consumer picks it up and advances the run. From the caller's side you start a run and watch it. There is no second queueing system to reason about.

The MCP server: capabilities for AI assistants

The MCP server exposes the same discover, start, watch, and recover surface to any Model Context Protocol client. It is the door that Claude, ChatGPT, Cursor, Staff actors, and your own agents use. Three things make it safe to expose publicly:

Org scoping is server-side. Your token resolves your organization. An assistant never sends or guesses the org ID.
Guardrails travel as resources. rule://getting-started, rule://authenticated-context, rule://prerequisites-first, rule://grounding, and rule://orkestia-auth-setup are delivered as first-class MCP context the assistant reads before acting. concept:// and knowledge:// resources orient it.
The transport is stateless. Streamable HTTP with no per-replica session state, so an assistant's context survives restarts and scale events.

It also ships two prompt templates (how_to_use_workflow_mcp, diagnose_workflow_run) and an open_app tool that renders the Orkestia console inside the chat for clients that support MCP Apps. Setup: Connect an AI assistant. Tool reference: MCP integration.

The data-vs-execution boundary

This is the heart of Zero Code Custody.

What the control plane stores

Workflow state, capability metadata, identity and RBAC, the telemetry you send to Lumen, the connection credentials you grant (scoped, encrypted at rest, never surfaced back), and — if you opted in — App Data rows and App Host site metadata. Enough to orchestrate, audit, recover, and serve apps you asked it to host.

What stays in your cloud

Runner compute and the resources workflows act on in your AWS / GCP / Azure / Kubernetes accounts. Cloud Deploy still writes to your S3/CloudFront. You can revoke connections. App Host is the exception you turn on per Identity app.

Two concrete illustrations:

Runners are a control plane, not a hosting plane. Orkestia provisions self-hosted runners in your cloud, mints short-lived registration tokens, and observes scaling. The runner binary talks to GitHub, not to Orkestia. A broken cloud connection means a broken group, not an Orkestia fallback. See Runners.
Compiled workflows run against your provider APIs using your authorized connections. Orkestia records the transitions, not your payloads as assets.
App Host is opt-in hosting: a claimed slug on Orkestia's shared pool, App Data for Postgres, Files on site MinIO (apphost.file.*), Buzz as a Nostr relay on a second hostname. You do not bring Helm. See App Host.

Because state is event-sourced and execution is externalized, Lumen can give you complete run history and drift signals without Orkestia ever holding your code or production data. See Drift detection & self-healing.

Ask your AI assistant

prompts

Read concept://engine and explain which parts of Orkestia you can operate through this MCP server and which you cannot.

Read knowledge://mcp/public-boundary and list what you should avoid doing on my behalf.

Show me the last five runs in my organization and where each one is in its state machine.

For AI agents

Component	How you reach it
Workflow engine	Through the MCP tools: `list_workflow_types`, `get_workflow_schema`, `start_workflow`, `watch_workflow`, `get_workflow_history`.
Identity	`whoami()` first. Org is resolved server-side. See `rule://authenticated-context`.
Lumen	A separate MCP server at `https://mcp-lumen.orkestia.dev/mcp`, not `mcp.orkestia.dev`.
Console	`open_app(route)` renders the Orkestia console inside clients that support MCP Apps.
Data lookups	Read-only data workflows (names containing `list`, `get`, `query`, `load`, `fetch`, or the `data.*` namespace). There is no separate query API. See `knowledge://mcp/discovery`.

Where to go next

Core concepts

The vocabulary and mental models behind the platform.

Workflows

How the event-sourced state machine executes runs.

Connect an AI assistant

Client configs, first prompts, and the prompt library.

Hybrid execution model

How AI design compiles into deterministic compositions.

The component names and surfaces above are stable. Per-workflow specifics live in the catalog at reference.orkestia.dev and via MCP discovery.

Quick Start

From zero to a first workflow run in your own cloud. Create an org, connect a cloud, then run a workflow from an AI assistant over MCP, the console, or the SDKs

Concepts at a Glance

One paragraph per Orkestia concept, workflows, compositions, MCP, DGI, Staff, agents, Agent Exchange, runners, Lumen, identity, App Data, App Host, Engram, DevKit, each with a prompt you can try and a link to the deep page