Skip to main content

Agent Status

Agent Connection Status Flow

The AstroFarm Agent transitions between four connection states depending on network availability, system power settings, and configuration health. Understanding these states helps diagnose and resolve connectivity issues faster.

Connection States​

  • Connected: Agent is fully online. Session active, heartbeat running, and contributor is available.

  • Failed. Reconnecting: Agent has lost connection and is automatically retrying. This resolves on its own when the network is restored (e.g., the machine is unlocked).

  • Disconnected: Agent goes offline. The contributor receives an offline alert email. The session is paused.

  • Connecting: Retrying automatically after a manual restart.

Typical Flow​

  • Agent launched, network active → Connected

  • Network drops (sleep, lock, or outage) → Failed. Reconnecting — retries automatically

    • If the network is restored → Connected (automatically reconnected, session resumes)

    • If retries are exhausted → Disconnected

  • From Disconnected:

    • Authentication error or invalid configuration → Disconnected (needs manual fix)

Status Summary​

  • Connected: Fully operational. No action needed.

  • Failed. Reconnecting: Temporary. Auto-resolves when the network is restored.

  • Disconnected: Offline. Restart the agent or restore the network to recover.

Troubleshooting Agent Disconnections on Healthy Networks​

The AstroFarm Agent can also be disconnected when the contributor's machine enters lock or sleep mode. This happens because the operating system suspends internet connectivity during these states, causing the agent to lose its connection to the AstroFarm platform.

Root Cause: If your machine enters sleep or hibernate mode during an active AstroFarm session, the agent will go offline, and contributors will receive an ‘offline’ notification. The Internet is not restored until the machine is manually unlocked or woken.

To prevent this, configure the system's power and lock timers so the machine never enters sleep or hibernate mode while the agent is running.

Windows​

Follow these steps to disable sleep mode on a Windows machine:

1. Open Power Options

Press the Start menu, search for the Control Panel, then navigate to Power Options.

2. Edit the active plan

Click on your active power plan, then select Change plan settings.

3. Configure basic plan timers

Set the following values in the basic plan settings screen:

  • Turn off display: As preferred (optional)

  • Put the computer to sleep: Never

4. Open Advanced Power Settings

Click Change advanced power settings to open the advanced dialog, then expand the Sleep section.

  • Sleep after: Never

  • Hibernate after: Never

  • Allow hybrid sleep: Off

5. Save the settings

Click OK to close the advanced dialog, then click Save changes on the plan settings screen. Changes take effect immediately.

MacOS​

Follow these steps to disable sleep mode on a Mac:

1. Open Energy Saver / Battery settings

Go to Apple menu > System Preferences, then click Battery or Energy Saver depending on your macOS version.

2. Apply settings to both tabs

Repeat the following for both the Battery tab and the Power Adapter tab:

  • Turn display off after: As preferred (optional)

  • Computer sleep timer: Never

  • Prevent sleeping when display is off: Enabled

  • Put hard disks to sleep when possible: Disabled

  • Enable Power Nap: Disabled

Best Practice: It is acceptable to allow the display to turn off to conserve power — this does not interrupt internet connectivity or affect the AstroFarm Agent. However, ensure the system itself never sleeps, hibernates, or enters any low-power state automatically while a session is active.

Locked Screen vs. Sleep Mode Locking the screen is safe as long as sleep mode is set to Never. A locked screen keeps the network active, and the agent remains connected. The internet is only cut off when the system actually enters sleep or hibernate.

Quick Reference​

  • Active / Unlocked: Network active — Agent online

  • Locked (sleep = Never): Network active — Agent online

  • Display off (sleep = Never): Network active — Agent online

  • Sleep / Hibernate: Network inactive — Agent disconnected