Updating Flutter Build Agents | FlightStack

Updating Agents

FlightStack agents include built-in update capabilities to ensure you’re always running the latest version with bug fixes and new features.

Update Methods

There are two ways to keep your agent updated:

Method	Description	When It Runs
Auto-Update	Automatically checks and installs updates	Between build jobs
Manual Upgrade	On-demand update via command	When you run the command

Auto-Update (Default)

By default, agents automatically check for and install updates between build jobs. This ensures your agent stays current without interrupting active builds.

How Auto-Update Works

1. Check interval - Agent checks for updates once per hour
2. Version comparison - Compares current version with latest release
3. Download - If newer version available, downloads the update
4. Install - Replaces the binary with the new version
5. Restart - Agent exits with code 100 to signal restart needed

Tip

Auto-updates only run between builds, never during an active build. Your builds won’t be interrupted.

Disabling Auto-Update

You can disable auto-updates if you prefer to manage updates manually:

For a single session:

flightstack-agent start --no-auto-update

Permanently via config:

# Edit ~/.flightstack/config.json
{
  "autoUpdate": false,
  ...
}

Manual Upgrade

Use the upgrade command to update the agent immediately:

flightstack agent upgrade

Output:

FlightStack Agent Upgrade
────────────────────────────────────────
Current version: v1.1.31

Checking for updates...

New version available: v1.1.32
Downloading v1.1.32...
Extracting...
Installing...

✓ Agent upgraded to v1.1.32

If the agent is running, restart it to use the new version.

Check for Updates Only

To see if an update is available without installing:

flightstack agent upgrade --check

Output (when update available):

FlightStack Agent Upgrade
────────────────────────────────────────
Current version: v1.1.31

New version available: v1.1.32

Run `flightstack agent upgrade` to update.

Output (when up-to-date):

FlightStack Agent Upgrade
────────────────────────────────────────
Current version: v1.1.32

✓ Agent is already on the latest version (v1.1.32)

Note

You can also use flightstack-agent upgrade directly if you prefer the standalone agent binary.

Update Process Details

When an update is applied (either auto or manual):

1. Download - New binary downloaded from GitHub releases
2. Backup - Current binary backed up temporarily
3. Replace - New binary copied to agent location
4. Permissions - Executable permissions set (Unix systems)
5. Cleanup - Backup and temp files removed
6. Rollback - If anything fails, backup is restored

Platform-Specific Downloads

Updates are downloaded for your specific platform:

Platform	Binary
macOS (Apple Silicon)	flightstack-agent-X.X.X-macos-arm64.tar.gz
macOS (Intel)	flightstack-agent-X.X.X-macos-x64.tar.gz
Linux	flightstack-agent-X.X.X-linux-x64.tar.gz
Windows	flightstack-agent-X.X.X-windows-x64.zip

Running as a Service

If your agent runs as a system service (launchd, systemd), it will automatically restart after an update:

macOS (launchd)

The agent exits with code 100 after update. launchd automatically restarts it:

<!-- In your .plist file -->
<key>KeepAlive</key>
<true/>

Linux (systemd)

Configure your service to restart on exit:

[Service]
Restart=always
RestartSec=5

Note

When running in foreground mode, you’ll need to manually restart the agent after an update.

Checking Current Version

To see what version you’re running:

flightstack-agent --version

Output:

FlightStack Agent v1.1.32 (build abc123)

Troubleshooting Updates

Update Fails to Download

Update failed: Connection timed out

Solutions:

• Check internet connectivity
• Verify access to github.com
• Check for proxy/firewall blocking downloads

Permission Denied

Failed to replace binary: Permission denied

Solutions:

• Ensure you have write permissions to the agent binary location
• On macOS/Linux, you may need sudo for system-wide installs
• Check if the binary is locked by another process

Rollback After Failed Update

If an update fails mid-process, the agent automatically restores from backup:

Update failed: Could not extract archive
Restoring previous version...
✓ Previous version restored

Best Practices

1. Keep auto-update enabled - Ensures you get bug fixes and security updates
2. Check version after issues - Run --version when troubleshooting
3. Review changelogs - Check release notes for breaking changes
4. Test in non-prod first - If running multiple agents, update one first

Release Notes

View the latest changes and release notes:

• GitHub Releases
• Changelog

Next Steps

• Running Agents - Learn about agent operation
• Auto-Start on Boot - Configure automatic startup
• Troubleshooting - Solve common issues