Quick Start

TL;DR

1. Create an account and an organization. The org scopes everything.
2. Connect a cloud with a scoped, revocable role. No access keys.
3. Run a workflow from an AI assistant over MCP, the console, or an SDK. Same engine, same catalog.
4. Optional: turn on Lumen for observability, deploy an app, or build one on Orkestia.

The fastest path is to connect an AI assistant to https://mcp.orkestia.dev/mcp and let it walk you through steps 2 and 3.

The shape of the journey

Orkestia is a privacy-first orchestrator. It holds workflow state and observability data. Cloud execution stays in your accounts. Apps you host on Orkestia (App Host + App Data) are an opt-in data and hosting plane — still isolated by identity, never a DSN in the frontend.

Prerequisites

1. Create your account and organization

Sign up with email or social login, then create an organization or accept an invite into one. The org is your tenancy boundary: it scopes connections, runs, Staff governance, Lumen data, and end-user identity.

Full walkthrough: User onboarding · Settings

2. Connect a cloud

Orkestia talks to your cloud through a cross-account role, never stored access keys. You create a role whose trust policy lets Orkestia's principal assume it. Orkestia then uses short-lived credentials per operation. Delete the role and access is revoked instantly. Every action shows up in your own audit log.

AWS is the reference connection. Once linked, every AWS-backed capability reuses it. GCP, Azure, Magalu Cloud, and Kubernetes follow the same delegation pattern with provider-native grants. See Cloud connections and DNS providers.

With an AI assistant

This is the canonical MCP flow, and the server enforces it through rule://prerequisites-first:

whoami()
get_workflow_schema("connection.setup")            → has_prerequisites: true, prerequisite_variants: ["aws", "gcp", …]
get_workflow_prerequisites("connection.setup", variant="aws")
  → a setup guide with Orkestia's principal ARN already filled in
# you create the role in your account, then hand back role_arn + external_id
start_workflow("connection.setup", { "provider_type": "aws", "role_arn": "…", "external_id": "…" })
watch_workflow(workflow_id)                        → COMPLETED

Prompt to paste:

Set up an AWS connection for my organization. Fetch the prerequisites first and show me exactly what to create. Do not start the workflow until I give you the role ARN and external ID.

Manually

Step by step (console, CloudFormation, or Terraform): AWS connections · DNS: DNS providers · Multi-cloud runners: Runners

3. Run your first workflow

In Orkestia, everything is a workflow: an event-sourced, resumable state machine with a typed input schema. Pick one capability and run it any of three ways.

whoami()                          → confirm identity; org resolved server-side
list_workflow_namespaces()        → what's available
list_workflow_types(prefix="…")   → candidates in one namespace
get_workflow_schema(type)         → required inputs, read_only, has_prerequisites
get_workflow_prerequisites(type)  → only if has_prerequisites is true
start_workflow(type, initial_data)
watch_workflow(workflow_id)       → follow to COMPLETED or FAILED

List the workflow namespaces my org can use and pick three safe read-only workflows to try.

Run a read-only workflow that lists my AWS S3 buckets and summarise the result.

Show me the schema for aws.s3.create_bucket. Do not run it.

npm i @ltinteg/workflows-sdk
pip install ltinteg-workflows-sdk

import { LtIntegWorkflowsClient, github } from "@ltinteg/workflows-sdk"

const client = new LtIntegWorkflowsClient({
  baseUrl: "https://workflow-api.orkestia.dev",
  token: process.env.ORKESTIA_TOKEN // org-member Bearer; org resolved server-side
})

const run = await github.startValidateToken(client, { /* typed inputs */ })
const output = await run.wait()
console.log(run.workflowId, run.stateName)

import os
from ltinteg_workflows_sdk import LtIntegWorkflowsClient
from ltinteg_workflows_sdk.github import auth

client = LtIntegWorkflowsClient(
    "https://workflow-api.orkestia.dev",
    token=os.environ["ORKESTIA_TOKEN"],
)
run = auth.start_validate_token(client, token="ghp_…")
print(run.workflow_id, run.terminal_status)

Deeper: Workflows · Building with DGI · Virtual workflows

4. (Optional) Turn on Lumen

Lumen is a separate host (https://lumen-api.orkestia.dev) from the workflow API. It is off until provisioned (403 LUMEN_NOT_PROVISIONED). An org admin enables a plan under Governance → Observability (Lumen), mints a lumk_ ingest key, then POSTs JSON to /api/logs/ingest or installs the collector. Lumen also has its own MCP server at https://mcp-lumen.orkestia.dev/mcp for triage.

Contract: Enable · Send data · Query API · Lumen MCP

5. (Optional) Deploy an app, or build one on Orkestia

Where to go next