Skip to content
FlightStack Docs

Running Agents

Running Agents

Section titled “Running Agents”

Once registered, your agent needs to be running to accept and execute builds. This guide covers starting, stopping, and managing agents.

Starting the Agent

Section titled “Starting the Agent”

Foreground Mode

Section titled “Foreground Mode”

Run the agent in the current terminal session:

Terminal window
flightstack agent start

Output:

FlightStack Build Agent
────────────────────────────────────────────────────
Agent: My-MacBook-Pro
API: https://api.flightstack.dev
ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890


✓ Agent is online


Waiting for builds... (Ctrl+C to stop)

The agent will:

  • Send heartbeats every 60 seconds
  • Poll for new jobs every 10 seconds
  • Execute any assigned builds
  • Report status back to FlightStack

Multi-URL Failover

Section titled “Multi-URL Failover”

Specify multiple API URLs for failover. The agent tries each URL in order and connects to the first available:

Terminal window
flightstack-agent start \
  --api-url http://localhost:5000 \
  --api-url https://api.flightstack.voostack.com

The agent will:

  • Try URLs in order (first takes priority)
  • Connect to the first successful API
  • Automatically reconnect to higher-priority URLs when available

Auto-Reconnection

Section titled “Auto-Reconnection”

When connected to a fallback URL, the agent periodically tries to reconnect to higher-priority URLs:

Terminal window
# Check for higher-priority URLs every 60 seconds (default: 30)
flightstack-agent start \
  --api-url http://localhost:5000 \
  --api-url https://api.flightstack.voostack.com \
  --reconnect-interval 60

This is useful for local development - the agent connects to your local API when running, but falls back to production if local is unavailable.

Using Profiles

Section titled “Using Profiles”

Start the agent with a specific configuration profile:

Terminal window
# Use config.dev.json instead of config.json
flightstack-agent start --profile dev

Or set via environment variable:

Terminal window
export FLIGHTSTACK_PROFILE=dev
flightstack-agent start

Background Mode (Daemon)

Section titled “Background Mode (Daemon)”

Run the agent in the background:

Terminal window
flightstack agent start --daemon

Output:

Starting agent in background...


✓ Agent started in background


PID: 12345
Log: /Users/you/.flightstack/agent.log


To stop: flightstack agent stop
To view status: flightstack agent status

The agent runs detached from your terminal session.

Stopping the Agent

Section titled “Stopping the Agent”

Stop a running agent:

Terminal window
flightstack agent stop

Output:

Stopping agent (PID: 12345)...
✓ Agent stopped

Checking Agent Status

Section titled “Checking Agent Status”

View the local agent status:

Terminal window
flightstack agent status

Output when running:

Local Agent Status
────────────────────────────────────────────────────
Name: My-MacBook-Pro
ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
API: https://api.flightstack.dev
Platform: macOS
Scope: Public (available to all organizations)


Process: Running (PID: 12345)


To stop: flightstack agent stop

Output when stopped:

Local Agent Status
────────────────────────────────────────────────────
Name: My-MacBook-Pro
ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
API: https://api.flightstack.dev
Platform: macOS
Scope: Public (available to all organizations)


Process: Stopped


To start: flightstack agent start
To start in background: flightstack agent start --daemon

Viewing Agent Logs

Section titled “Viewing Agent Logs”

When running in daemon mode, logs are written to:

Terminal window
# View logs
tail -f ~/.flightstack/agent.log


# View errors
tail -f ~/.flightstack/agent.error.log

Example log output:

[14:32:15] FlightStack Build Agent
[14:32:15] Agent: My-MacBook-Pro
[14:32:15] ✓ Connected
[14:32:15] ✓ Agent is online
[14:32:15] Waiting for builds...
[14:35:22] New build job received
[14:35:22]   Repository: my-app
[14:35:22]   Branch: main
[14:35:22]   Commit: abc1234
[14:35:22]   Platform: iOS

Build Execution

Section titled “Build Execution”

When a build is assigned, the agent:

  1. Receives job details

    • Repository URL
    • Branch and commit
    • Build steps and configuration

  2. Prepares workspace

    • Creates a temporary directory
    • Clones the repository
    • Checks out the specified commit

  3. Executes build steps

    • Runs each step in order
    • Streams logs to FlightStack
    • Uploads artifacts as they’re created

  4. Reports completion

    • Final status (success/failure)
    • Build duration
    • Any error messages

  5. Cleans up

    • Removes temporary files
    • Returns to idle state

Resource Management

Section titled “Resource Management”

Disk Space

Section titled “Disk Space”

The agent monitors disk space and will stop accepting builds if free space falls below 10 GB:

Agent paused: Insufficient disk space: 8.5GB available, 10GB required

Free up space or configure a different workspace to resume.

Concurrent Builds

Section titled “Concurrent Builds”

By default, agents run one build at a time. This ensures:

  • Maximum resources for each build
  • No interference between builds
  • Predictable build times

Memory & CPU

Section titled “Memory & CPU”

Builds use your machine’s full resources. For large projects:

  • Close unnecessary applications
  • Consider dedicated build machines
  • Monitor memory during builds

Troubleshooting

Section titled “Troubleshooting”

Agent Won’t Start

Section titled “Agent Won’t Start”

Already running:

Agent is already running (PID: 12345)
Use: flightstack agent stop

Stop the existing agent first, then start again.

Not registered:

Agent not registered. Run: flightstack agent register

Register the agent before starting.

Connection Failed

Section titled “Connection Failed”
Connection failed
Error: Connection timed out


Please check:
  1. API is running at https://api.flightstack.dev
  2. Agent token is valid
  3. Agent is registered in the system

Possible causes:

  • Network connectivity issues
  • Firewall blocking outbound HTTPS
  • Invalid or expired token

Try:

Terminal window
# Test connectivity
curl https://api.flightstack.dev/health


# Re-register if token is invalid
flightstack agent register

Heartbeat Failures

Section titled “Heartbeat Failures”
Heartbeat failed: Connection refused

The agent will retry automatically. If persistent:

  • Check network connectivity
  • Verify the API is accessible
  • Check for proxy/firewall issues

Build Failures

Section titled “Build Failures”

If builds fail unexpectedly:

  1. Check the build logs in FlightStack app
  2. Verify Flutter is working: flutter doctor
  3. Ensure Xcode is configured (iOS): xcode-select -p
  4. Check the agent logs for errors

Next Steps

Section titled “Next Steps”