The Panel shows "Agent Offline" or "Connection Refused" when it cannot reach the Opterius Agent on the server. All write operations — creating accounts, changing PHP versions, issuing certificates — flow through the Agent, so this blocks all server management until resolved.
Follow these steps in order.
Step 1: Check the Agent Service
SSH into the server and check the systemd status:
systemctl status opterius-agent
If the service is stopped or failed:
systemctl start opterius-agent
systemctl status opterius-agent
If it starts cleanly, go back to the Panel and refresh. The server should come online within a few seconds.
If the service fails to start, proceed to Step 3 to check logs before trying again.
Step 2: Test the Health Endpoint
With the service running, confirm it is actually listening:
curl http://127.0.0.1:7443/health
Expected response:
{"status": "ok", "version": "1.x.x"}
If curl hangs or returns "Connection Refused", the agent is not listening on the expected port. Check the configured port in /etc/opterius/agent.conf — the port value must match 7443 (or whatever the Panel has recorded for this server).
Step 3: Check Agent Logs
journalctl -u opterius-agent -n 50
Look for startup errors, port conflicts, or license failures. Common log messages and their meanings:
| Log message | Cause |
|---|---|
address already in use |
Another process is on port 7443 — find and stop it |
failed to load config |
/etc/opterius/agent.conf is missing or malformed |
license validation failed |
Agent started but blocked — see License Invalid |
invalid secret key |
secret_key in agent.conf doesn't match the Panel's stored secret |
Common Causes
Agent crashed. The most common cause after a kernel update or OOM event. Restart it:
systemctl restart opterius-agent
If it keeps crashing, check logs continuously:
journalctl -fu opterius-agent
Wrong port. If agent.conf has a non-default port, the Panel record for this server must be updated to match. Edit the server in Server Mode → Settings → Agent and update the port number.
Token mismatch. The secret_key in /etc/opterius/agent.conf and the secret stored in the Panel database must be identical. If they diverge (e.g. after manually editing agent.conf), every request from the Panel will be rejected with 401.
To fix: copy the current secret from /etc/opterius/agent.conf and update the Panel's server record, or regenerate the secret from the Panel and paste it back into agent.conf, then restart the agent.
Firewall blocking port 7443. The Agent only listens on 127.0.0.1 by default, so an inbound firewall rule should not be needed when Panel and Agent are on the same machine. However, if your iptables or ufw rules are blocking loopback traffic (non-standard), allow it:
# ufw
ufw allow in on lo to any port 7443
# iptables
iptables -I INPUT -i lo -p tcp --dport 7443 -j ACCEPT
Panel on a separate machine. By default the Agent binds only to 127.0.0.1 for security. If the Panel is on a different host, the Agent must be started with the --public flag (or equivalent config setting) to listen on a public interface, and port 7443 must be opened in the server's firewall — restricted to the Panel's IP only.