Auto-Start on Boot

Auto-Start on Boot

For always-on CI/CD, you’ll want your build agent to start automatically when your machine boots. FlightStack provides built-in commands to configure this.

Quick Setup

Install the agent as a startup service:

flightstack agent install

Remove the startup service:

flightstack agent uninstall

That’s it! The CLI handles all platform-specific configuration.

Platform Details

macOS

How It Works

On macOS, FlightStack uses launchd (Apple’s service management framework) to start the agent automatically.

Installation

flightstack agent install

This creates a Launch Agent plist at:

~/Library/LaunchAgents/com.flightstack.agent.plist

Output:

Installing FlightStack Agent as startup service...

Created: ~/Library/LaunchAgents/com.flightstack.agent.plist

✓ Agent installed as startup service!

The agent will start automatically on login.

To start now:     launchctl start com.flightstack.agent
To stop:          launchctl stop com.flightstack.agent
To uninstall:     flightstack agent uninstall

Manual Control

# Start the service now (without rebooting)
launchctl start com.flightstack.agent

# Stop the service
launchctl stop com.flightstack.agent

# Check if running
launchctl list | grep flightstack

Configuration

The generated plist includes:

• RunAtLoad: Starts when you log in
• KeepAlive: Restarts if the agent crashes
• StandardOutPath: Logs to ~/.flightstack/agent.log
• StandardErrorPath: Errors to ~/.flightstack/agent.error.log

Tip

The agent starts on login, not at system boot. This ensures your user session is available for Keychain access and code signing.

Uninstallation

flightstack agent uninstall

This stops the service and removes the plist file.

Linux

How It Works

On Linux, FlightStack uses systemd user services to manage the agent.

Installation

flightstack agent install

This creates a systemd service at:

~/.config/systemd/user/flightstack-agent.service

Output:

Installing FlightStack Agent as startup service...

Created: ~/.config/systemd/user/flightstack-agent.service

✓ Agent installed as startup service!

The agent will start automatically on login.

To start now:     systemctl --user start flightstack-agent
To stop:          systemctl --user stop flightstack-agent
To view logs:     journalctl --user -u flightstack-agent -f
To uninstall:     flightstack agent uninstall

Enabled user lingering - agent will run even when logged out.

Manual Control

# Start the service
systemctl --user start flightstack-agent

# Stop the service
systemctl --user stop flightstack-agent

# Check status
systemctl --user status flightstack-agent

# View logs
journalctl --user -u flightstack-agent -f

User Lingering

The install command enables “user lingering” which allows the service to run even when you’re not logged in:

loginctl enable-linger $USER

This is essential for headless build servers.

Configuration

The generated service file includes:

• Restart=on-failure: Auto-restart on crashes
• RestartSec=10: Wait 10 seconds before restart
• Logs to ~/.flightstack/agent.log

Uninstallation

flightstack agent uninstall

This stops and disables the service, then removes the service file.

Windows

How It Works

On Windows, FlightStack uses Task Scheduler to start the agent at login.

Installation

flightstack agent install

This creates a scheduled task named FlightStackAgent.

Output:

Installing FlightStack Agent as startup service...

✓ Agent installed as startup service!

The agent will start automatically on logon.

To start now:     schtasks /run /tn FlightStackAgent
To stop:          flightstack agent stop
To uninstall:     flightstack agent uninstall

Manual Control

# Start the task
schtasks /run /tn FlightStackAgent

# View task info
schtasks /query /tn FlightStackAgent /v

# Stop the agent
flightstack agent stop

Task Scheduler GUI

You can also view and manage the task in Task Scheduler:

1. Open Task Scheduler (taskschd.msc)
2. Find “FlightStackAgent” in the task list
3. Right-click to Run, Disable, or Delete

Configuration

The scheduled task is configured to:

• Run at logon
• Run with highest privileges
• Not stop if the computer switches to battery

Uninstallation

flightstack agent uninstall

This removes the scheduled task.

Verifying Installation

After installation, verify the startup service is configured:

macOS

# Check if plist exists
ls -la ~/Library/LaunchAgents/com.flightstack.agent.plist

# Check if loaded
launchctl list | grep flightstack

Linux

# Check service status
systemctl --user status flightstack-agent

# Check if enabled
systemctl --user is-enabled flightstack-agent

Windows

# Check task exists
schtasks /query /tn FlightStackAgent

Testing the Setup

1. Install the service

   flightstack agent install

2. Start it manually (to test without rebooting)

   macOS

   launchctl start com.flightstack.agent

   Linux

   systemctl --user start flightstack-agent

   Windows

   schtasks /run /tn FlightStackAgent

3. Verify it’s running

   flightstack agent status

4. Check in FlightStack app

   • Go to Build Agents
   • Verify your agent shows as “Online”

5. Test reboot (optional)

   • Restart your computer
   • Verify agent starts automatically

Logs Location

When running as a service, logs are written to:

Platform	Log File
macOS	~/.flightstack/agent.log
Linux	~/.flightstack/agent.log or journalctl --user -u flightstack-agent
Windows	%USERPROFILE%\.flightstack\agent.log

Troubleshooting

Service Won’t Start

Check the logs for errors:

tail -100 ~/.flightstack/agent.log

Common issues:

• Agent not registered (run flightstack agent register first)
• Invalid token (re-register the agent)
• Network issues (check connectivity)

Agent Not Registered

You must register the agent before installing as a service:

flightstack agent register
flightstack agent install

Permission Issues (macOS)

If you see permission errors:

# Ensure LaunchAgents directory exists
mkdir -p ~/Library/LaunchAgents

# Check permissions
ls -la ~/Library/LaunchAgents/

Systemd Issues (Linux)

# Reload systemd after manual changes
systemctl --user daemon-reload

# Check for errors
journalctl --user -u flightstack-agent --no-pager -n 50

Task Not Running (Windows)

1. Open Task Scheduler
2. Find FlightStackAgent
3. Check the “Last Run Result” column
4. Right-click > Properties > check configuration

Updating

When you update the FlightStack CLI, the startup service continues to work because it points to the executable. After updating:

1. Stop the running agent
2. Update the CLI
3. Restart the agent (or reboot)

# Stop
flightstack agent stop

# Update (example for Homebrew)
brew upgrade flightstack

# Start
flightstack agent start

Removing Auto-Start

To stop the agent from starting automatically:

flightstack agent uninstall

This removes the startup configuration but keeps your agent registered. You can still start the agent manually with flightstack agent start.