Build Agents Overview

Build agents are the workhorses of FlightStack. They’re self-hosted machines that execute your build pipelines, running on your own hardware.

Why Self-Hosted Agents?

No Build Limits

Run unlimited builds without paying per-minute charges. Your hardware, your rules.

Faster Builds

Use your powerful Mac Pro or custom build servers for blazing-fast builds.

Full Control

Your source code never leaves your network. Complete privacy and security.

Custom Setup

Install any tools, SDKs, or dependencies you need. No container limitations.

How Agents Work

┌─────────────────┐         ┌─────────────────┐
│   FlightStack   │◀───────▶│   Build Agent   │
│     Server      │  HTTPS  │   (Your Mac)    │
└─────────────────┘         └─────────────────┘
         │                           │
         │                           │
         ▼                           ▼
  ┌─────────────┐            ┌─────────────┐
  │  Pipeline   │            │   Clones    │
  │  Scheduler  │            │  Your Code  │
  └─────────────┘            └─────────────┘

Agent polls for work - The agent periodically checks for queued builds
Job assigned - When a matching build is found, it’s assigned to the agent
Code cloned - Agent clones your repository locally
Build executed - Steps are run (tests, builds, deploys)
Results reported - Logs and artifacts are uploaded back to FlightStack

Agent Capabilities

Each agent reports what it can build based on the installed software:

Capability	Requirement	Detects
iOS	macOS + Xcode	`xcodebuild -version`
Android	Android SDK	`ANDROID_HOME` or `flutter doctor`
Web	Flutter	Always available

Agent States

Agents report their status to FlightStack:

State	Icon	Description
Online	🟢	Ready to accept builds
Busy	🟡	Currently running a build
Offline	🔴	Not running (no recent heartbeat)
Disabled	⚫	Manually disabled by admin

An agent is considered online if it has sent a heartbeat within the last 2 minutes.

Agent Scopes

Agents can be scoped to control which organizations can use them:

Public Agents

Available to all organizations you belong to
Good for personal use or shared infrastructure
Default when no organization is specified

Private Agents

Restricted to a specific organization
Ideal for enterprise/team environments
Configured during registration with --org flag

# Public agent (available to all your orgs)
flightstack agent register

# Private agent (only for specific org)
flightstack agent register --org <organization-id>

Resource Requirements

Minimum Requirements

Resource	iOS Builds	Android Builds	Web Builds
RAM	8 GB	4 GB	2 GB
Storage	50 GB free	30 GB free	10 GB free
CPU	4 cores	2 cores	2 cores

Recommended Specifications

For optimal performance, especially with large Flutter projects:

Resource	Recommended
RAM	16 GB+
Storage	SSD with 100 GB+ free
CPU	8+ cores
OS	Latest stable (macOS 14+, Ubuntu 22.04+)

Heartbeat & Health Monitoring

Agents send regular heartbeats containing:

Status - Online, busy, etc.
Disk space - Available storage
Memory - Available RAM
CPU - Current utilization

If disk space falls below 10 GB, the agent will stop accepting new builds until space is freed.

Security

Agent security features:

Unique tokens - Each agent has a unique authentication token
Encrypted communication - All traffic uses HTTPS/TLS
Local builds - Code is cloned locally, never uploaded
Token rotation - Tokens can be regenerated if compromised

Multiple Agents

You can run multiple agents for:

Platform coverage - Mac for iOS, Linux for Android
Parallel builds - Multiple simultaneous builds
Redundancy - Backup agents for high availability

Builds are automatically load-balanced across available agents based on:

Platform capability match
Organization scope
Agent availability
Current load

Next Steps

Ready to set up your first agent?