Runners & Execution Environments

TL;DR

• A runner is where work physically runs, and it is always in your cloud. Orkestia provisions, registers, scales, and heals it. Compute, data, and egress stay with you.
• Two entities: a runner group (the long-lived, configured pool) and runner executions (launched runners that come and go with demand).
• Scaling is a reconcile loop, bounded by min and max. Webhooks nudge it; they are never the source of truth.
• AWS, Azure, and Kubernetes run production fleets today. GCP, DigitalOcean, and Magalu Cloud are beta.
• Everything is a runner.* workflow, so an assistant over MCP can provision, inspect, and scale groups like any other capability.

Control plane vs execution plane

The control plane drives runners through runner.* workflows on the engine. Because those are ordinary workflows, provisioning a fleet is just another DAG with full history, per-group locking, and async transitions.

The two core entities

Kinds (backend × purpose × integration)

A group is not “an AWS runner.” It stores three enums:

The create wizard’s Runner type step is the backend-kind list, filtered by the cloud connection you picked. Full catalog, required config keys, and per-kind pages: Runner groups.

Connect a cloud first (AWS connections, Cloud connections) and pick placement through network profiles. A broken cloud connection means a broken group. There is deliberately no Orkestia compute fallback.

Warm pools and capacity

A cold runner has to provision compute, pull an image, and register before it picks up a job. Warm pools keep a floor of ready runners so jobs start immediately. Capacity is governed per group:

{
  "scale": { "min": 0, "max": 10, "idle_timeout_s": 300 },
  "labels": ["self-hosted", "orkestia", "prod-builds"]
}

• min: the warm floor. 0 means scale to zero when idle.
• max: the hard ceiling. Orkestia never exceeds it, even if the queue grows.
• idle_timeout_s: how long a runner sits idle before it is reaped.

Reconcile-loop scaling

A per-group controller continuously compares the live pool against your policy and converges it toward min and max. Job-source workflow_job events are a best-effort nudge that makes the loop react immediately. They are never the source of truth.

sequenceDiagram
  participant GH as Job source
  participant CP as Runner control plane
  participant Cloud as Your cloud
  Note over CP: reconcile loop converges pool → min/max (continuous)
  GH->>CP: workflow_job.queued (webhook nudge)
  CP->>CP: reconcile (queued vs busy, bounded by max)
  CP->>Cloud: launch runner execution (async transition)
  Cloud->>GH: register + poll for job
  GH->>CP: workflow_job.completed (nudge)
  CP->>CP: reconcile: maybe scale down after idle_timeout

Registration is pull, not push: Orkestia hands the runner a short-lived registration token and the runner registers itself with the job source. No long-lived secrets sit on disk.

Group lifecycle

Drift detection and self-healing

Runners are long-lived infrastructure in an account you also touch directly. Reality drifts from intent: a runner dies, a token expires, a teardown half-completes. Periodic health checks detect drift and self-heal: unhealthy runners are deregistered and reaped, orphaned registrations are swept, failed scale-ups are retried.

Common cases the healer handles: expired registration tokens (new runners cannot join; existing ones keep working), provider quota at scale-up (queue backs up; existing runners unaffected), orphaned runners after a partial teardown, unreachable runner images.

Observability

Every runner action emits structured signals on the same transition bus the rest of the platform uses. Group provisioned, scaled up, scaled down, unhealthy, archived, and per-job pickup and completion all flow into Lumen.

Runners vs agent runner groups

Ask your AI assistant

List my runner groups with provider, state, and scaling policy.

Show me the schema for provisioning a Kubernetes runner group. If it has prerequisites, fetch them.

Which of my runner groups are unhealthy, and what does the last health check say?

Scale group <group_id> to min 2, max 8. Show me the plan and wait for my confirmation.

For AI agents

Status

AWS, Azure, and Kubernetes run production fleets; GCP, DigitalOcean, and Magalu Cloud are beta. Job sources: GitHub Actions (GA) and GitLab (purpose=gitlab_runner). Kind catalog: Runner groups.