Registering an Agent

Registering an Agent

Before an agent can execute builds, it must be registered with FlightStack. This guide walks through the registration process.

Prerequisites

Before registering, ensure you have:

• FlightStack CLI installed (Installation Guide)
• Logged in to FlightStack (flightstack login)
• Required build tools installed (Flutter, Xcode, etc.)

Tip

The agent automatically uses your CLI authentication token. If you’re logged in via flightstack login, you don’t need to provide a separate token.

Registration Process

1. Verify Login

   Ensure you’re logged in:

   flightstack login

2. Run Registration

   Register your machine as an agent:

   flightstack agent register

3. Enter Agent Name

   You’ll be prompted for a name (defaults to your hostname):

   Agent name (My-MacBook-Pro):

4. System Detection

   The CLI automatically detects your system capabilities:

   System Information:
     Platform: macOS
     OS Version: macOS 14.2
     Xcode: 15.1
     Flutter: 3.16.5
     Dart: 3.2.3
   
   Capabilities:
     iOS: ✓
     Android: ✓
     Web: ✓

5. Registration Complete

   Upon success:

   ✓ Agent registered successfully!
   
   Agent ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
   
   Next step: flightstack agent start

Registration Options

Custom Agent Name

flightstack agent register --name "iOS-Build-Server"

Organization-Scoped Agent

Register an agent for a specific organization (private agent):

flightstack agent register --org <organization-id>

Note

Find your organization ID in the FlightStack app under Organization Settings.

Profile Support

Use profiles to manage separate agent configurations (e.g., for local development):

~/.flightstack/config.dev.json

# Register with a profile
flightstack-agent register --profile dev

You can also set the profile via environment variable:

export FLIGHTSTACK_PROFILE=dev
flightstack-agent register

Non-Interactive Registration

For scripted/automated setup:

flightstack-agent register \
  --name "CI-Server-01" \
  --org "org-id-here"

What Gets Registered

During registration, the following information is collected and stored:

Data	Purpose
Agent name	Display name in UI
Platform	macOS, Linux, or Windows
OS version	For compatibility checks
Xcode version	iOS build capability
Flutter version	Build environment info
Dart version	Build environment info
Capabilities	What platforms can be built

Agent Configuration File

After registration, configuration is stored at:

macOS / Linux

~/.flightstack/agent.json

Windows

%USERPROFILE%\.flightstack\agent.json

The file contains:

{
  "agentId": "a1b2c3d4-...",
  "token": "eyJhbGciOiJI...",
  "apiUrl": "https://api.flightstack.dev",
  "agentName": "My-MacBook-Pro",
  "platform": "macOS",
  "organizationId": null,
  "organizationName": null
}

Caution

Never share your agent token! It grants full access to execute builds as your agent.

Re-Registration

If you need to re-register an agent (new token, different org, etc.):

flightstack agent register

You’ll be prompted:

This machine is already registered as an agent.
Agent: My-MacBook-Pro
ID: a1b2c3d4-...

Re-register and replace existing? (y/n)

Verifying Registration

After registration, verify the agent appears in FlightStack:

# List all agents
flightstack agent list

# Or check local status
flightstack agent status

Output:

Build Agents (1):
────────────────────────────────────────────────────────────

My-MacBook-Pro
  ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
  Status: 🔴 Offline
  Scope: 🌐 Public
  Platform: macOS
  Capabilities: iOS, Android, Web
  Builds: 0 total, 0 successful

────────────────────────────────────────────────────────────

Troubleshooting Registration

”Not logged in” Error

# Log in first
flightstack login

# Then register
flightstack agent register

”Agent already registered”

If you want to keep the existing registration:

• Answer “n” when prompted to re-register
• Run flightstack agent start to start the existing agent

To force re-registration:

• Answer “y” to replace the existing registration
• Or delete the config file: rm ~/.flightstack/agent.json

Flutter Not Detected

Ensure Flutter is in your PATH:

# Check Flutter
flutter doctor

# Add to PATH if needed
export PATH="$PATH:/path/to/flutter/bin"

Xcode Not Detected (macOS)

# Install Xcode from App Store, then:
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -license accept

Next Steps

After registration:

1. Start the Agent
2. Configure Auto-Start
3. Create a Pipeline