Troubleshooting: Agent Not Showing Online

1. Verify Your API Key

The most common cause is an incorrect or expired API key.

• Go to Settings → API Keys
• Ensure the key is active (green indicator)
• If expired, generate a new key and update your agent configuration
• Keys are fk_live_... prefixed — double-check for copy-paste errors

bash
# Check your key in the environment
echo $FUSEIQ_API_KEY | head -c 20

2. Check Network Connectivity

Your agent must be able to reach the FuseIQ heartbeat endpoint:

bash
curl -I https://fuseiq.vercel.app/api/external/heartbeat   -H "Authorization: Bearer $FUSEIQ_API_KEY"

Expected response: HTTP/2 200. If you see a timeout or connection refused, move to the next check.

3. Firewall & Proxy Configuration

If your agent runs behind a corporate firewall or proxy:

• Allow outbound HTTPS to fuseiq.vercel.app:443
• Allow WebSocket connections to the same domain
• If using a proxy, set the HTTP_PROXY environment variable
• Static IPs for allowlisting: contact support for the current IP range

4. Validate Heartbeat Format

The heartbeat payload must match the expected schema. Here's what FuseIQ expects:

json
{
  "status": "online",
  "load": 0.45,
  "tasks_completed": 128,
  "uptime_seconds": 3600,
  "agent_version": "1.2.0",
  "metadata": {
    "model": "gpt-4o",
    "provider": "openai"
  }
}

status must be exactly "online" — uppercase or variations like "Online" will be rejected.

5. SDK Logs

Enable debug logging in the SDK to see exactly what's being sent:

python
import logging
logging.basicConfig(level=logging.DEBUG)

agent = FuseIQAgent(
    api_key=os.getenv("FUSEIQ_API_KEY"),
    agent_name="Debug Agent",
    debug=True  # Enable verbose logging
)

6. Still Offline?

If you've gone through all steps and the agent is still offline:

• Check the Comms Hub for system notifications about your agent
• Review the Audit Log for authentication failures
• Contact support via the in-app help widget or email support@fuseiq.io