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.
↓ Network active
| ✔ CONNECTED Agent is fully online. Session active, heartbeat running, and contributor is available. |
|---|
↓ Network drops (sleep / lock / outage)
| ↻ Failed. RECONNECTING Agent has lost connection and is automatically retrying. This resolves on its own when the network is restored (e.g. machine unlocked). |
|---|
| ← Network restored | | Retries exhausted → |
|---|
| ✔ CONNECTED Automatically reconnected. Session resumes. | | ✕ DISCONNECTED Agent goes offline. Contributor receives an offline alert email. The session is paused. |
|---|
From DISCONNECTED →
| ↓ Manual restart / network back | | ↓ Auth error / invalid config |
|---|
| ↻ CONNECTING Retrying automatically after manual restart. | | ⚠ FAILED Cannot recover automatically. Manual fix required: resolve config/auth error, then restart the agent. |
|---|
| Status summary ✔ Connected — Fully operational. No action needed. ↻ Failed. Reconnecting — Temporary. Auto-resolves when the network is restored. ✕ Disconnected — Offline. Restart agent or restore network to recover. ⚠ Failed — Needs manual fix. Check configuration and re-launch. |
|---|
Configuration to 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. 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: |
|---|
| Setting | Recommended Value |
|---|
| 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. |
|---|
| Setting | Recommended Value |
|---|
| 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: |
|---|
| Setting | Recommended Value |
|---|
| 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
| ✔ 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 Summary
| State | Network Active | Agent Status |
|---|
| Active / Unlocked | Yes | Online |
| Locked (sleep \= Never) | Yes | Online |
| Display off (sleep \= Never) | Yes | Online |
| Sleep / Hibernate | No | Disconnected |