Core Philosophy

TL;DR

• Pillar 1, Zero Code Custody. Orkestia never holds your source code or your data plane. It holds only the scoped credentials you grant it, encrypted at rest and revocable by you. On AWS that is a role trust with no static keys.
• Pillar 2, AI-first but deterministic. AI designs the plan (through DGI or an assistant over MCP). The plan compiles into a composition that runs identically every time, with no model in the hot path.
• Pillar 3, Customer-owned execution. Compute, resources, and data live in your account, under your IAM and your audit trail.
• One sentence: Orkestia knows what should happen and what did happen. It never takes custody of the doing.

Orkestia is built on one premise: you should be able to orchestrate your cloud and automate your operations without handing a third party custody of your code, your data, or your compute. Every architectural decision below follows from that.

Pillar 1: Zero Code Custody

The reference integration is the AWS cross-account role trust, not a credential upload. You run a bootstrap template (CloudFormation or Terraform, provided during connection setup) in your own account. It creates a role Orkestia can assume. Nothing else changes hands. Other providers (GCP, Azure, Kubernetes, Cloudflare, and the rest) do not offer that trust model, so for them you create a scoped key or token and Orkestia stores it encrypted; the section below covers both cases.

How it works

When a workflow needs to touch your AWS account, the engine calls sts:AssumeRole against your role, gated by a per-organization external ID in the trust policy. The result is a set of short-lived session credentials (about one hour), minted per run and never cached across runs.

sequenceDiagram
    participant Eng as Orkestia workflow engine
    participant STS as AWS STS (your account)
    participant Res as Your AWS resources
    Eng->>STS: AssumeRole(role_arn, external_id)
    STS-->>Eng: short-lived session credentials (~1h)
    Eng->>Res: provision / read using session creds
    Note over Eng,Res: credentials expire; nothing is cached across runs

The trust policy is the whole security boundary, and it lives in your account:

{
  "Effect": "Allow",
  "Principal": { "AWS": "arn:aws:iam::<orkestia-account>:root" },
  "Action": "sts:AssumeRole",
  "Condition": {
    "StringEquals": { "sts:ExternalId": "<per-org-secret>" }
  }
}

What Orkestia stores, and what it never stores

Orkestia is not a general secrets manager. It stores only the credential each connection needs, encrypted, and never surfaces it back to the console, the API, or an AI assistant after creation. Every credential is scoped by you and revocable from your side: rotate the token or delete the service account and the connection fails closed. It never writes to your IAM: roles and permissions are created and changed only by you, in your account.

The same rule applies to AI assistants

When an assistant connected over MCP needs a connection that does not exist yet, it does not ask you for keys. It calls get_workflow_prerequisites and receives a setup guide with Orkestia's principal already filled in. You create the role in your account. The assistant only ever receives the role ARN and external ID that the workflow schema declares as inputs. Read rule://prerequisites-first on the server or the MCP integration page.

Why it matters

• Privacy. Your code and data never transit or rest on Orkestia infrastructure.
• Compliance. Actions happen under your IAM principal, in your CloudTrail, inside your compliance boundary.
• Trust under breach. On AWS there are no static keys, only short-lived sessions. On other providers the stored credential is scoped to what you granted and encrypted at rest. Revocation is always unilateral: delete the role, rotate the token, or remove the service account, and the connection fails closed. It is marked degraded and dependent workflows fail with a clear reason.
• Least privilege. The permissions pack is scoped to the apps you subscribe to. Adding capability is an explicit re-bootstrap or re-grant, never a silent privilege grab.

Pillar 2: AI-first, but deterministic

Orkestia refuses the false choice between "smart but unpredictable" and "reliable but rigid". It separates the two phases of automation:

AI designs, compiled workflows execute

You describe an outcome in plain language. The AI reasons over the catalog of registered capabilities and assembles a plan. That plan is not what runs in production. It compiles into a deterministic composition: a DAG of atomic, versioned operations that executes identically every time.

Every atomic workflow follows the platform's 3-state pattern (PENDING → COMPLETED | FAILED) with strict input and output schemas, per-run concurrency locks, and an event-sourced state machine. An assistant that runs capabilities over MCP invokes the same validated workflows everyone else does. It cannot improvise against your production cloud.

Grounding: the AI may only say what it can see

The MCP server publishes a rule://grounding resource. It tells an assistant to describe Orkestia only from tool results: the catalog, schemas, and run history. A registered type is a capability, not evidence of a production run. A catalog total is a capability count, not "N production workflows". This is the design-time version of the same discipline: the AI proposes from what is declared, and the engine decides what actually happens.

Why it matters

• Reproducibility. The same composition produces the same execution. Diff two runs and the difference is your inputs.
• Auditability. Every run is an event-sourced sequence of typed transitions, readable with get_workflow_history.
• Reliability. No LLM latency, token limits, or non-determinism in the execution path.
• Governance. Designs are explicit artifacts that can be reviewed and approved before they run. That is where Staff comes in.

Pillar 3: Customer-owned execution

The first two pillars converge here: the resources, data, and compute that result all live in your account.

When Cloud Deploy deploys a static site, the bucket, CDN distribution, certificate, and DNS records are created in your cloud account. When a build runs, it runs on a runner you own. Orkestia orchestrates the provisioning and remembers the declared shape. It does not host the result.

Drift detection closes the loop

Orkestia holds the declared shape, but the resources live in your account where they can change out of band. A reconcile loop periodically compares the recorded shape against the live cloud, produces a repair plan, and can bring resources back to the declared state. See Drift detection & self-healing.

Why it matters

• Data residency. Resources and their data never leave your account, region, or jurisdiction.
• Cost transparency. Cloud spend appears on your bill, under your tags. No platform markup on compute.
• No lock-in of assets. Stop using Orkestia tomorrow and your buckets, distributions, and runners are still yours.
• Blast-radius isolation. Connections can be pinned per site or per org, so one workflow's problem is bounded by IAM scope you control.

The pillars are one idea

Put plainly: Orkestia knows what should happen and what did happen. It never takes custody of the doing. That is what makes it safe to point an AI assistant at production infrastructure.

Ask your AI assistant

Read rule://grounding and rule://prerequisites-first, then summarise what you are and are not allowed to claim or do on Orkestia.

I want to connect my AWS account. Fetch the prerequisites for connection.setup with variant "aws" and show me the trust policy I need to create.

Which of the workflows under the aws.s3 namespace are read-only, and which ones would you ask me to confirm before running?

For AI agents

Where to go next