Agent Showing Offline

An agent shows as Offline in Command Center when it hasn’t checked in within the expected polling interval (default: 60 seconds). This is usually a connectivity or configuration issue.

Common Causes

1. Network / Firewall Blocking

The most common cause. The agent makes outbound HTTPS requests to the Ambient API.

Required outbound access:

Destination	Port	Protocol
api.ziviso.africa	443	HTTPS
*.ziviso.africa	443	HTTPS (CDN assets)

Check your firewall or proxy logs for blocked requests from the agent process (AmbientAgent.exe on Windows, ambient-agent on Linux).

If your environment uses a proxy, configure the agent’s proxy setting:

// C:\ProgramData\Ambient\agent-config.json
{
  "proxyUrl": "http://proxy.company.com:8080"
}

2. Agent Service Not Running

Windows:

Get-Service -Name "Ambient*"
# If stopped:
Start-Service -Name "AmbientAgent"

Linux (deb install):

systemctl status ambient-agent
# If stopped:
sudo systemctl start ambient-agent

3. Incorrect API URL in Config

Check that agent-config.json points to the correct server:

{
  "serverUrl": "https://api.ziviso.africa/api/v1"
}

For dev/staging environments this will differ. Confirm the URL with your Ambient admin.

4. Clock Skew (TLS Failure)

Ambient uses certificate-based security. If the device clock is more than 5 minutes off, TLS handshakes fail.

Windows: w32tm /resync /force Linux: sudo timedatectl set-ntp true

5. Outdated Agent Version

Agents more than 2 major versions behind may be unable to connect. Update from:

Windows: Ambient-Agent-Setup-latest.exe — runs an in-place upgrade. Linux: sudo dpkg -i ambient-agent_latest_amd64.deb

Checking Agent Logs

Windows: C:\ProgramData\Ambient\logs\agent.log Linux: ~/.config/ambient/logs/agent.log or journalctl -u ambient-agent -n 100

Look for HTTP error codes (403, 502, 0 = no network) to identify the exact failure.

Still Offline?

If none of the above resolve the issue, open a support ticket from Help & Support → Submit Ticket and attach the agent log file.