Deployment Models
Orkestia runs as a split-plane system: a managed control plane that Orkestia operates, and an execution plane that lives entirely inside your cloud accounts. The control plane orchestrates, stores workflow state, and observes; it never holds your code or your data. This page explains where each part runs, how your accounts connect, how apps get built and deployed, and exactly where the privacy boundary sits.
If you are new to the platform, start with Concepts and the Deployment overview; for the connection and deploy walkthroughs see AWS Connections and Cloud Deploy.
The two planes
Control plane (Orkestia-managed)
The workflow engine, DGI, Staff governance, Lumen, the MCP surface, and the identity layer. Orkestia runs these. They orchestrate work and store workflow state + observability data — never customer source or runtime data.
Execution plane (your cloud)
Every side-effecting operation — provisioning S3/CloudFront, launching runners, building apps, mutating infrastructure — executes against your connected cloud accounts using cross-account roles you grant. The compute and the data stay with you.
The boundary is the core design commitment: Zero Code Custody. Orkestia is a control plane, not a hosting plane. The phrase that recurs across the platform — "the compute always lives in the customer's cloud; Orkestia holds none of it" — is literal.
- Workflow engine(event-sourced state)
- DGI — AI workflow design
- Staff — agent governance
- Lumen — observability
- MCP surface
- Identity / multi-tenancy
- Cross-account IAM role
- S3 + CloudFront (apps)
- Self-hosted runnersECS/Fargate, EC2, K8s, ...
- Your other cloud resources
- GitHub
- Workflow engine→ assume role, scoped calls →Cross-account IAM role
- Cross-account IAM role→S3 + CloudFront (apps)
- Cross-account IAM role→Self-hosted runners
- Cross-account IAM role→Your other cloud resources
- Self-hosted runners→ registers directly with →GitHub
- Workflow engine→ state + events only →Lumen — observability
workflow.transition payloads). It does not persist your repository contents, build artifacts, or application runtime data — those stay in your cloud.How execution reaches your cloud: connections
Before Orkestia can do anything in your account, you grant it scoped access through a connection. For AWS this is a cross-account IAM role that the control plane assumes; for GitHub it is an App/OAuth/PAT grant used for repo access, webhooks, and runner registration. Connections are organization-scoped and are the canonical "prerequisite" for most workflows.
| Provider | Mechanism | What it authorizes |
|---|---|---|
| AWS | Cross-account IAM role (assume-role) | S3, CloudFront, ACM, Route53, ECS/Fargate, EC2, IAM — per the workflow's needs |
| GCP / Azure / Magalu / Kubernetes | Provider-native credential/grant | Alternative compute + storage targets — see Cloud Connections |
| GitHub | App / OAuth / PAT | Repo read, webhook registration, short-lived runner registration tokens |
| DNS (Route53 / Cloudflare) | Provider grant | Custom-domain validation + records |
has_prerequisites: true, the MCP/get_workflow_prerequisites flow returns a setup guide with Orkestia's own principal pre-filled, so you grant exactly the trust needed — nothing broader. See AWS Connections and MCP integration.Because access is delegated rather than copied, a broken or revoked connection means that app or group simply stops working — there is no Orkestia-side fallback that silently holds your resources. This is the privacy boundary expressed operationally.
App deployment: GitHub → your cloud (Cloud Deploy / SPAD)
Cloud Deploy (internally SPAD) is the reference deployment model and the most mature app on the platform. You connect a GitHub repo + branch and a cloud account; Orkestia provisions per-site infrastructure and runs your build pipeline — all inside your account.
For an AWS target, a site is provisioned with isolated, per-site resources:
| Resource | Purpose |
|---|---|
s3_bucket | Static asset storage |
cloudfront_distribution | CDN + HTTPS termination |
cloudfront_oac | Origin Access Control (locks the bucket to CloudFront) |
acm_certificate | SSL via ACM, validated through your DNS connection |
The build runs on a managed build runner in your own cloud — not on Orkestia compute. The control plane orchestrates the stages and streams progress; the bytes never leave your account.
sequenceDiagram participant GH as GitHub participant CP as Orkestia control plane participant R as Build runner (your cloud) participant AWS as S3 + CloudFront (your cloud) GH->>CP: push / release webhook CP->>R: start build (clone → install → build) R->>R: produce artifacts in-account R->>AWS: upload artifacts CP->>AWS: invalidate CloudFront cache CP-->>CP: record deploy state + events
A push to the linked branch triggers an auto-deploy workflow; a manual trigger or re-publish runs its own variant; rollback re-publishes a prior artifact set without rebuilding, so it completes in seconds. The engine serializes concurrent deploys of the same site with a Postgres advisory lock, so two quick pushes don't race. See the Cloud Deploy guide for the full UX and the workflow catalog for the exact spad.* workflow names and inputs.
spad.* provider variants; check the catalog for per-provider coverage. Cloud Deploy is static / SPA today — server-side rendering and edge targets are roadmap, not current scope.Compute deployment: self-hosted runners
Runners provisions self-hosted capacity inside your cloud (or a DevKit laptop) — the same split-plane shape applied to CI and agent compute. Orkestia is the control plane: it provisions the environment for the group's backend_type, optionally mints short-lived registration tokens via a GitHub App or GitLab connection, and drives scaling from a reconcile loop. For GitHub-integrated groups the runner binary registers directly with GitHub, not with Orkestia — Orkestia only observes.
| Concept | Meaning |
|---|---|
| Runner group | Long-lived pool: backend_type + purpose + integration_type + scaling policy |
| Runner execution | A single launched runner serving jobs or an agent session on that group |
| Scaling | Reconcile loop converges the pool to the group's min/max; job-source events nudge it to react faster |
Key consequences of the model:
- Compute stays in your cloud — you pay the provider directly; Orkestia never holds runner compute (
devkitis the laptop exception). - No cross-cloud pool — a group targets one kind; jobs don't spill from AWS to GCP within a group.
- Bounded by policy — Orkestia never exceeds your configured max, even under queue pressure, by design.
fargate, ec2_vm, ec2_auto_scaling) is GA end-to-end, and Azure and Kubernetes groups run production fleets today; GCP, DigitalOcean, and Magalu kinds have partial coverage. See the kind catalog and Runner management before committing to a beta kind.Kubernetes-native execution
Kubernetes is a first-class execution target, not an afterthought. The platform itself runs on Kubernetes, and runner environments can be provisioned as in-cluster Deployments via the Kubernetes runner library. Workflows that touch clusters compose k8s.* primitives, and the same drift-detection and self-healing model that guards cloud resources applies to Kubernetes objects.
This is what lets Orkestia treat "deploy to my cluster" and "deploy to S3+CloudFront" as the same orchestration shape — different target resources, identical control-plane mechanics (event-sourced state, advisory-lock serialization, Kafka-backed async steps). For how drift and reconciliation work, see Drift detection & self-healing.
Where state and async live
| Concern | Where it runs | Notes |
|---|---|---|
| Workflow state machine | Control plane | Event-sourced; Postgres advisory locks for concurrency |
| Long-running steps (build, upload, provision waits) | Async via Kafka (workflow.transition) | Consumed by the workflow Kafka consumer — the one async path |
| Side effects (cloud mutations, builds) | Your cloud, via assumed role | The actual work |
| Observability signals | Control plane (Lumen) | Events/metrics on the platform Kafka bus |
This separation is why a deploy can be slow (e.g. a CloudFront invalidation backlog) without being failed, and why rollback is cheap: the control plane is replaying recorded state, while the heavy lifting already happened — and happened in your account.
Privacy boundary recap
The result is a control plane you can trust with orchestration and audit, while custody of code and data — and the bill for compute — stays entirely on your side of the line. This is the foundation the rest of the platform builds on: see Security & compliance and the Hybrid execution model.