Cloud runners
Cloud runners
Section titled “Cloud runners”Cloud runners are on-demand build VMs FlightStack provisions and tears down per build. They’re an opt-in escape valve for when your self-hosted agents are saturated, on holiday, or absent entirely.
When to use them
Section titled “When to use them”Most production teams run a hybrid setup:
- Self-hosted Mac mini farm — iOS builds, cheap, fast for warmed-cache builds.
- Cloud runners for burst — when there are more queued iOS builds than Mac minis, cloud runners absorb the overflow.
- Cloud runners full-time — small teams without dedicated hardware.
If you’re an iOS shop, self-hosted is almost always cheaper in steady state. Cloud runners shine when load is spiky (PR storms, demo days) or non-iOS.
Enabling
Section titled “Enabling”Cloud runners are organization-scoped. Enable them via the API:
curl -X POST https://api.flightstack.voostack.com/organizations/$ORG_ID/cloud-runners/enable \ -H "Authorization: Bearer $TOKEN"…or the Cloud runners tab in Organization settings.
Configuration
Section titled “Configuration”| Setting | What it controls |
|---|---|
| Image | macOS Xcode version, Ubuntu version, Windows version. |
| Machine type | CPU + RAM combo. Larger = faster but more expensive. |
| Max concurrent instances | Upper bound on parallel cloud runners. Caps cost. |
| Idle minutes before shutdown | Keep warm pool for instant pickup, at the cost of small idle time. |
| Monthly budget (cents) | Hard ceiling. Runs queue once exceeded — no surprise bills. |
| Burst allowed over | self-hosted (default) or none — prefer self-hosted when present. |
Read or update via PUT /organizations/{orgId}/cloud-runners/config.
How scheduling works
Section titled “How scheduling works”When a build is triggered:
- The scheduler looks for an eligible self-hosted agent with capacity.
- If none found and cloud runners are enabled (with budget remaining), a cloud runner is provisioned matching the build’s platform.
- If both fail, the build queues until either an agent frees up or budget refreshes.
You can force a build onto a cloud runner by labeling the job, but the default behavior is the right answer for most teams.
Cost control
Section titled “Cost control”- Set a monthly budget. This is the strongest lever. Builds simply queue when exceeded.
- Pick the smallest machine that hits your SLA. macOS builds are usually wall-clock bound
by Xcode, not CPU —
c2-standard-4is enough. - Bring more self-hosted agents. Cheapest cores you’ll ever have.
- Tighten idle shutdown. 1–2 minutes is plenty for warm-pool latency.
Observability
Section titled “Observability”Usage is reported per day, per machine type:
curl https://api.flightstack.voostack.com/organizations/$ORG_ID/cloud-runners/usage/current \ -H "Authorization: Bearer $TOKEN"The dashboard’s Cloud runners tab graphs the same numbers. Configure a notification job on a scheduled pipeline (e.g. daily) to drop a usage summary in Slack.
Forced termination
Section titled “Forced termination”If a cloud runner gets stuck (rare — usually a hung Xcode), force-terminate:
curl -X POST https://api.flightstack.voostack.com/organizations/$ORG_ID/cloud-runners/instances/$INSTANCE_ID/terminate \ -H "Authorization: Bearer $TOKEN"The in-flight build is marked as failed.
See also
Section titled “See also”- Cloud runners API — endpoint reference
- Build agents — the self-hosted side
- Pricing