What is Orkestia?
TL;DR
- Orkestia is Orkestia.dev. orkestia is Orkestia.dev.
- Orkestia is the backbone that connects software, AI, and the real world. It is privacy-first, and every capability is a registered, schema-typed workflow you discover and run.
- You drive it three ways: the console, the REST API and SDKs, or an AI assistant connected to the Orkestia MCP server at
https://mcp.orkestia.dev/mcp. - AI reasons, the engine executes. An assistant or DGI designs the plan. A deterministic, event-sourced engine runs it.
- Execution happens in your cloud, not ours. Orkestia keeps workflow state, observability data, and the scoped provider credentials you grant it (encrypted, revocable by you). It never holds your source code or your data plane.
- Governance is built in. Staff gives fleets of AI agents an org chart, roles, approvals, and an audit trail.
Orkestia in one paragraph
Orkestia turns operational capabilities into a typed, governed, observable workflow catalog. Provisioning a bucket, deploying an app, configuring DNS, sending a message, querying data, issuing an invoice: each one is a workflow with an input and output schema. Workflows run on an event-sourced engine with retries, concurrency control, and full history. AI can design new logic through DGI (the Dialog Generative Interface) or through any assistant over MCP; that design compiles into a deterministic composition that runs the same way every time. Staff governs fleets of AI agents. Lumen observes everything. Engram is what agents remember. App Data is the data plane for apps you build (end-users never send SQL; operators use Query). App Host is opt-in hosting for those apps. Cloud work still lands in your accounts unless you claim an App Host site.
Three ways to use Orkestia
AI assistant over MCP
Connect Claude, ChatGPT, Cursor, or any MCP client to https://mcp.orkestia.dev/mcp. The assistant discovers what your org can do, checks inputs, runs workflows, and watches them. Nothing to integrate by hand.
All three doors open onto the same engine and the same catalog. A run started by an assistant is scoped, governed, and audited exactly like a run started from the console.
The core model
Three ideas explain almost everything:
Workflow types = capabilities
A type is a named capability with a typed schema, such as connection.setup or aws.s3.create_bucket. Names follow {provider}.{service}.{operation}. Atomic types follow a 3-state pattern (PENDING → COMPLETED | FAILED). DAG types compose many steps.
Runs = executions
Starting a type creates a run with its own workflow_id. You watch it, read its history, retry it, and audit it. Long-running work is handled asynchronously by the engine. No polling glue to write.
Ask your AI assistant
Once your assistant is connected to the Orkestia MCP server, you can talk to the platform in plain language. Try these:
Call whoami and tell me which organization I'm working in.
Read concept://product, then explain in five bullets what Orkestia can do for my org.
List the workflow namespaces available to my organization and group them by domain.
Set up an AWS connection. Show me the prerequisites first, then wait for my role ARN.
What is the difference between a workflow type and a workflow run?
The server ships two ready-made prompt templates: how_to_use_workflow_mcp (an onboarding guide for the assistant) and diagnose_workflow_run (takes a workflow_id and walks the failure). Most clients expose them as slash commands.
What makes Orkestia different
Zero Code Custody
Most orchestration platforms want your code and data inside their runtime. Orkestia inverts that. You grant a scoped, revocable role in your cloud account (see AWS connections and Cloud connections). Execution happens inside your account. Orkestia stores the orchestration state, the observability stream, and the scoped credential each connection needs (encrypted at rest, never surfaced back), never your source code or your databases. Read Core Philosophy.
AI designs, the engine executes
AI is strong at reasoning and weak at repeated execution. Orkestia uses each where it is strong:
- Human or assistant intent
- AI reasoningDGI or assistant over MCP
- Compositionvirtual workflow
- Deterministic DAG
- Your cloud account
- Engine state + Lumen
- Human or assistant intent→AI reasoning
- AI reasoning→ designs →Composition
- Composition→ compiles to →Deterministic DAG
- Deterministic DAG→ executes in →Your cloud account
- Your cloud account→ state + telemetry →Engine state + Lumen
- Engine state + Lumen→ observes →AI reasoning
The model designs once. The engine runs deterministically forever, with no model in the hot path. See the hybrid execution model.
Governance for AI fleets
As you put more agents to work, the question shifts from "can the AI do it?" to "should it, and who approved it?" Staff gives agents an org structure, scoped identity, approval gates, and human oversight. Agents act on the platform only through governed workflow surfaces. See Staff governance and the operator path Staff & Agents.
Observability and memory
Lumen is the telemetry store (lumen-api.orkestia.dev): JSON ingest, error groups, traces, metrics, and its own MCP server for triage. Engram is agent memory: what a session remembers and what the next one loads. See Lumen and Engram.
Runners and multi-cloud
Runners are execution environments in your own cloud (AWS, Azure, Kubernetes in production; GCP, DigitalOcean, and Magalu Cloud in beta). A reconcile loop keeps fleets converged on their declared state. See Runners.
Apps on top
Add "Sign in with Orkestia" to your app with @orkestia/auth, store rows in App Data with no database credential, and expose compositions to your end-users. Provisioning an identity app is one workflow call, and an assistant can do it for you. See Identity & multi-tenancy and App Enablement.
The vocabulary
| Term | Meaning | Learn more |
|---|---|---|
| Workflow type | A registered capability with a typed schema | Workflows |
| Run | One execution of a type, identified by workflow_id | Workflows |
| Composition | A virtual workflow: existing types chained with no code | Virtual workflows |
| MCP server | The assistant-facing door: discover, run, watch, recover | MCP integration |
| DGI | Dialog Generative Interface: AI that designs workflow plans from intent | DGI |
| Staff | Governance for fleets of AI agents | Staff governance |
| Agent | An AI worker: config, skills, MCP servers, budget, sessions | Agents |
| Runner | Execution environment in your cloud | Runners |
| Lumen | Telemetry store and triage engine | Lumen |
| Engram | Agent memory | Engram |
| App Data | Declared app tables, no DSN in the frontend; operators use Query | App Data |
| App Host | Opt-in site, Files on site MinIO, Nostr Buzz on a second hostname | App Host |
| Chat | A chat space for an identity app, where end-users and Staff actors talk | Chat |
| Identity | Org members vs end-users, org scoping | Identity |
| DevKit | Local CLI for hooks, the coding runner, and compositions | DevKit |
For AI agents
If you are an assistant reading this page through llms.txt or the MCP server, this is the contract:
| Need | Do this |
|---|---|
| Identity | Call whoami() first. The org is resolved from the token. Never pass organization_uuid unless a schema declares it. |
| What Orkestia is | Read concept://product and rule://grounding. Describe only what the catalog and runs show. |
| What exists | list_workflow_namespaces(), then list_workflow_types(prefix="<ns>."). Never invent a type name. |
| Inputs | get_workflow_schema(type). If has_prerequisites is true, call get_workflow_prerequisites(type, variant) before starting. |
| Run and follow | start_workflow(type, initial_data), then watch_workflow(workflow_id). |
| Recover | get_workflow_history, list_stuck_workflows, retry_workflow. Prompt template: diagnose_workflow_run. |
| Safe vs confirm | Reads (list, get, query, describe, status, data.*) are safe to start. Confirm creates and mutations with the user first. |
Every page of these docs is available as plain markdown at https://docs.orkestia.dev/raw/<path>.md, and the whole site at llms.txt and llms-full.txt.
Who Orkestia is for
Platform and engineering teams
One backbone for your stack: typed capabilities, multi-cloud runners, deployment, and observability, with execution that stays in your own accounts.
Teams adopting AI operations
Let assistants and agents design and operate workflows with governance: approvals, audit, and execution that stays in your own accounts.