Core Concepts

The mental model behind Orkestia, workflows, MCP, DGI, Staff, agents, Agent Exchange, runners, Lumen, identity, billing, App Data, App Host, Engram, and DevKit, with a reading order and a map from each concept to its MCP namespaces and tools

TL;DR

Every capability is a workflow. Provisioning, deploying, messaging, querying, invoicing: each is a registered, schema-typed workflow.
Same engine, several doors. Console, SDKs, DGI, and AI assistants over the MCP server all drive one event-sourced engine.
AI designs, the engine executes, your cloud does the work. Compositions compile AI reasoning out of the hot path. Runners live in your accounts.
Governance, memory, and markets are first class. Staff governs agent fleets. Lumen observes. Engram remembers. Agent Exchange is how orgs hire each other's actors.
Read in order. The pages below build on each other. Each one ends with prompts to try and a "For AI agents" contract.

Running actors this week? Concepts here stay the model. The customer path — model provider, agent runner group, hire, sessions, tokens, coding agents — is Staff & Agents. Hiring another org's actor is Agent Exchange.

The model in one breath

A workflow is a capability with a typed input and output contract. Starting one creates a run with its own workflow_id that you watch, inspect, and retry. AI assistants discover and invoke capabilities over MCP. DGI turns intent into a plan; that plan compiles into a composition, your deterministic logic with no code. Each agent is an agent config (skills, tools, budget) launched as sessions on your runners, and Staff governs those agents with org structure, approvals, and oversight. Agent Exchange is the labor market for those actors across organizations. Cloud runs execute inside your cloud account. Lumen observes. Engram is what agents remember. App Data is declared app state. App Host is opt-in hosting. Identity scopes it all to an organization and, for apps you build, to your end-users.

AI assistants (MCP)
DGI
designs intent
Composition
deterministic virtual workflow
Workflows
typed capabilities
Staff
governance
Runner
in YOUR cloud
Lumen
observability
Identity
Your end-users
Sign in with Orkestia

AI assistants (MCP)→ discover + invoke →Workflows
DGI→ compiles to →Composition
Composition→Workflows
Staff→ approvals + oversight →AI assistants (MCP)
Workflows→ run →Runner
Runner→Lumen
Identity→ scopes →Workflows
Identity→ exposes to →Your end-users

Privacy by construction. Orkestia stores workflow state, observability data, and the encrypted connection credentials you grant, not your code and not your data plane. Runs execute in your accounts on runners you own. See Security & compliance.

Read in this order

1. Workflows

Types vs runs, the event-sourced state machine, DAGs, and compositions. The primitive everything else uses.

2. DGI

The Dialog Generative Interface: intent in, validated plan out, compiled to a deterministic composition.

3. Staff

Governance for fleets of AI agents: org structure, engine-enforced RBAC, approvals, audit.

4. Agents

What an AI worker is: config, workflow-backed skills, MCP servers, memory, budget, sessions.

5. Runners

Execution environments in your cloud, with reconcile-loop scaling and self-healing.

6. Lumen

Telemetry store: ingest, error groups, traces, metrics, and the Lumen MCP.

7. Identity

Members vs end-users, automatic org scoping, "Sign in with Orkestia".

8. Billing & seats

Subscription, seats for humans and AI actors, end-user seats, add-ons, budgets.

9. App Data

Declared app tables with injected principals. End-users never send SQL; operators use Query.

10. App Host

Opt-in site hosting: website, App Data, Files on site MinIO, Nostr Buzz on a second hostname.

11. Engram

Agent memory: fingerprint dedupe, last_k and pack recall.

12. DevKit

Local CLI for webhook redirect, the coding runner, tickets, and compositions.

13. Agent Exchange

Hire and list Staff actors across orgs. Ledger, not funds. Operator path: Agent Exchange.

Chat

Chat spaces for identity apps: end users sign in with their app identity, Staff actors answer in the conversation.

Hybrid execution model

The advanced track: why intent and execution are decoupled.

How the pieces relate

Concept	One-line role	In your cloud?	Stored by Orkestia
Workflow / run	A typed capability and its execution	Executes in your cloud	State and history
MCP server	The assistant door onto the engine	No (control plane)	Nothing beyond the runs it starts
DGI	AI that designs workflow plans from intent	No (reasoning)	Plan artifacts
Composition	Your deterministic, no-code logic	Executes in your cloud	Definition and state
Staff	Governance for AI agents	No (control plane)	Org structure, approvals
Agent Exchange	Cross-org hire of Staff actors	Execution stays in each party's cloud	Listings, deals, leases, ledger — not funds
Agents	Config, skills, sessions	Sessions run in your cloud	Configs, session state, cost entries
Runner	Where execution physically happens	Yes, your account	Connection metadata only
Lumen	Observability over runs	No	Telemetry you send, derived groups and traces
Identity	Org and end-user scoping	No	Identity records
Billing and seats	Subscription, seats, usage	No	Subscription and usage records
App Data	Declared app rows (opt-in data plane)	No (platform store)	Virtual structures, records, serving instances
App Host	Opt-in website / process / Buzz	Shared Orkestia pool when you claim a site	Site metadata, not your zip as source
Engram	Agent memory	No	Memories and recalls
DevKit	Local CLI	Runs on your machine	Config and API token only

Concept to MCP map

If you drive Orkestia from an assistant, this is where each concept surfaces on the MCP server.

Concept	Namespaces you will see	Tools and resources that matter
Workflows	everything	`list_workflow_types`, `get_workflow_schema`, `start_workflow`, `watch_workflow`; `concept://workflow-types-vs-instances`
Compositions	`composition.`, `control.`; saved ones run as `virtual.<uuid>@<version>`	`get_workflow_dag`; `concept://dag`
DGI	`dgi.`, `ai.`, `chat.*`	`get_workflow_definition`
Staff	`staff.`, `audit.`	`audit.workflow-run.query` for evidence
Agent Exchange	`exchange.`, `data.exchange.`	List then schema; never pass the other org's UUID
Agents	`agents.*`	agent tokens return `agent_uuid` and `staff_actor_uuid` from `whoami`
Runners	`runner.*`	`list_stuck_workflows` for stalled provisioning
Lumen	separate server at `mcp-lumen.orkestia.dev`	`list_logs`, `get_trace`, `resolve_error_group`, and more
Identity	`identity.`, `connection.`	`whoami`; `rule://authenticated-context`; `rule://orkestia-auth-setup`
Billing	`subscription.`, `stripe.`	reads are safe; confirm mutations
App Data	`data.appdata.`, `appdata.instance.`, `appdata.credential.`, `appdata.query.`	reads in `data.*` are safe to start; instance provision is a mutation
App Host	`apphost.*`	claim/publish need a live Identity app; never echo DSNs or relay keys
Engram	`agents.memory-*`	flags live on the agent config
Chat	`buzz.`, `data.buzz.`	`buzz.space.status` and featured `data.buzz.*` reads are safe; admin verbs need a person. See Chat

Two producers, one consumer. DGI (AI) and compositions (deterministic) both produce workflow plans. The engine is the single consumer that runs them. An AI-designed flow and a hand-built composition compile to the same DAG shape. See Hybrid execution model.

Ask your AI assistant

prompts

Read concept://product and give me the concept map of my organization: which namespaces are active and what each domain does.

Explain, with concept://workflow-types-vs-instances, why the catalog total is not the number of workflows that ran.

List my recent runs across all types and group them by concept: infrastructure, deploy, agents, data.

DGI-driven design and self-healing runner reconciliation are alpha and evolving. Capabilities are described here at the model level; the authoritative per-workflow contract lives in the workflow reference.

Where this leads

Connect an AI assistant

Client configs, first prompts, and the prompt library.

Run agents & actors

Hire a Staff actor, attach skills, launch a session on an agent runner group.

Agent Exchange

List those actors, or hire one another org published.

Build with DGI

From a natural-language goal to a compiled composition.

Browse the full catalog

Every workflow type with its typed schema, prerequisites, and outputs.

Expose workflows to end-users

Build a multi-tenant app with "Sign in with Orkestia".

SDKs

Node and Python workflow clients; @orkestia/auth for end-users.

For deeper tracks see the guides, the advanced section, and operations.

Connect an AI Assistant

Plug Claude, ChatGPT, Cursor, Claude Code, or any MCP client into the Orkestia MCP server, then run your first workflow by talking. Includes a prompt library and the rules the server gives your assistant

Workflows

The execution model in depth. Workflow types versus runs, the event-sourced state machine, DAGs, how an assistant drives it over MCP, and compositions that compile into deterministic engine config